From f1f2f260b9116a52b4e76bb9aa586089cbdfc903 Mon Sep 17 00:00:00 2001 From: Tobias Gesellchen Date: Sun, 24 May 2026 11:05:23 +0200 Subject: [PATCH] docs: fix on-device multi-speaker claim in deployment overview MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit 'Each speaker needs its own install' is only true when the firmware binds port 8000 to loopback (older devices, issue #196). Devices that expose the port on the LAN can run one on-device AfterTouch and point other LAN speakers at it — same as a Raspberry Pi. Qualify the cell accordingly. Co-Authored-By: Claude Sonnet 4.6 --- docs/guides/CLOUD-DEPLOY-WALKTHROUGH.md | 36 ++++++++-------- docs/guides/DEPLOYMENT-OVERVIEW.md | 44 ++++++++++---------- docs/guides/EXTERNAL-HOST-WALKTHROUGH.md | 26 ++++++------ docs/guides/ON-DEVICE-INSTALL-WALKTHROUGH.md | 16 +++---- 4 files changed, 61 insertions(+), 61 deletions(-) diff --git a/docs/guides/CLOUD-DEPLOY-WALKTHROUGH.md b/docs/guides/CLOUD-DEPLOY-WALKTHROUGH.md index d765965..20ab304 100644 --- a/docs/guides/CLOUD-DEPLOY-WALKTHROUGH.md +++ b/docs/guides/CLOUD-DEPLOY-WALKTHROUGH.md @@ -7,7 +7,7 @@ This scenario is useful when you don't have an always-on machine at home but you already have a cloud server (Hetzner, DigitalOcean, Coolify, etc.). For local deployments (Raspberry Pi, NAS, home server) see -[EXTERNAL-HOST-WALKTHROUGH.md](EXTERNAL-HOST-WALKTHROUGH.md). +[EXTERNAL-HOST-WALKTHROUGH.md](EXTERNAL-HOST-WALKTHROUGH.md). For a comparison of all deployment options see [DEPLOYMENT-OVERVIEW.md](DEPLOYMENT-OVERVIEW.md). @@ -15,12 +15,12 @@ For a comparison of all deployment options see ## How cloud deployment differs from a local host -| | Local host | Cloud host | -|--|-----------|-----------| -| Speaker discovery | Automatic (mDNS on the LAN) | **Disabled** — cloud can't reach your LAN | -| Speaker migration | Via the AfterTouch web UI | **Via `soundtouch-cli` on your local machine** | -| URL scheme | `http://` is fine on a LAN | **HTTPS required** — speakers validate the certificate | -| Audio routing | Stays on the LAN (AfterTouch only proxies metadata) | Stays on the LAN — audio never transits the cloud server | +| | Local host | Cloud host | +|-------------------|-----------------------------------------------------|----------------------------------------------------------| +| Speaker discovery | Automatic (mDNS on the LAN) | **Disabled** — cloud can't reach your LAN | +| Speaker migration | Via the AfterTouch web UI | **Via `soundtouch-cli` on your local machine** | +| URL scheme | `http://` is fine on a LAN | **HTTPS required** — speakers validate the certificate | +| Audio routing | Stays on the LAN (AfterTouch only proxies metadata) | Stays on the LAN — audio never transits the cloud server | > **Audio does not flow through AfterTouch.** The cloud server only handles > authentication tokens and URL discovery. Music data goes directly between @@ -172,10 +172,10 @@ The speaker should appear in the list. 2. Run or refresh the health checks. 3. Apply any QuickFixes shown, especially: - | Warning | Action | - |---------|--------| + | Warning | Action | + |-------------------------------------------------|---------------------------------------------| | *Speaker reports an empty ``* | Click **Pair account** / **Apply QuickFix** | - | *INTERNET_RADIO source is a stale stub* | Click **Remove INTERNET_RADIO source** | + | *INTERNET_RADIO source is a stale stub* | Click **Remove INTERNET_RADIO source** | 4. Reboot the speaker after any QuickFix that requires it, then re-run health checks. @@ -260,14 +260,14 @@ To minimise downtime, use your cloud provider's restart policy ## Troubleshooting -| Symptom | First check | -|---------|------------| -| Speaker shows certificate error | HTTPS certificate is not trusted — ensure your reverse proxy serves a valid Let's Encrypt cert | -| Migration fails with "connection refused" | Speaker can't reach `soundtouch.example.com:443` — check your server's firewall | -| Source TuneIn 1005 error | TuneIn not in speaker's source list — follow Step 6 | -| AfterTouch logs "discovery timeout" every 5 min | Set `DISCOVERY_ENABLED=false` | -| Devices tab empty after migration | Add the speaker manually by IP (Step 4) | -| `margeAccountUUID` still empty after QuickFix | Re-run Health QuickFix and reboot again | +| Symptom | First check | +|-------------------------------------------------|------------------------------------------------------------------------------------------------| +| Speaker shows certificate error | HTTPS certificate is not trusted — ensure your reverse proxy serves a valid Let's Encrypt cert | +| Migration fails with "connection refused" | Speaker can't reach `soundtouch.example.com:443` — check your server's firewall | +| Source TuneIn 1005 error | TuneIn not in speaker's source list — follow Step 6 | +| AfterTouch logs "discovery timeout" every 5 min | Set `DISCOVERY_ENABLED=false` | +| Devices tab empty after migration | Add the speaker manually by IP (Step 4) | +| `margeAccountUUID` still empty after QuickFix | Re-run Health QuickFix and reboot again | For more detail see [TROUBLESHOOTING.md](TROUBLESHOOTING.md) and [MIGRATION-GUIDE.md](MIGRATION-GUIDE.md). diff --git a/docs/guides/DEPLOYMENT-OVERVIEW.md b/docs/guides/DEPLOYMENT-OVERVIEW.md index b063f6b..198c837 100644 --- a/docs/guides/DEPLOYMENT-OVERVIEW.md +++ b/docs/guides/DEPLOYMENT-OVERVIEW.md @@ -7,15 +7,15 @@ three ways to run it — pick the one that fits your situation. ## Which deployment is right for me? -| | Local external host | Cloud / VPS | On-device | -|--------------------------|---------------------|-------------|-----------| -| **What it means** | AfterTouch runs on a Raspberry Pi, NAS, or PC on your home LAN. | AfterTouch runs on a remote server you own (Hetzner, DigitalOcean, Coolify, …). | AfterTouch runs directly on the SoundTouch speaker itself. | -| **Extra hardware** | Yes — an always-on machine at home | No — uses a server you already have | No | -| **Multiple speakers** | Easy — one instance for all LAN speakers | Yes — one instance, managed remotely | Each speaker needs its own install | -| **Speaker migration** | Via the AfterTouch web UI | Via `soundtouch-cli` on your local machine | Via SSH into the speaker | -| **HTTPS needed** | No — HTTP on the LAN is fine | **Yes** — speakers require a valid certificate | No | -| **Updates** | Update the host once | Update the server once | SSH into each speaker | -| **Good for** | Most households; want a central dashboard | No always-on home machine; already have a VPS | Single-speaker; no extra hardware at all | +| | Local external host | Cloud / VPS | On-device | +|-----------------------|-----------------------------------------------------------------|---------------------------------------------------------------------------------|-----------------------------------------------------------------------------------------------------------------------------------| +| **What it means** | AfterTouch runs on a Raspberry Pi, NAS, or PC on your home LAN. | AfterTouch runs on a remote server you own (Hetzner, DigitalOcean, Coolify, …). | AfterTouch runs directly on the SoundTouch speaker itself. | +| **Extra hardware** | Yes — an always-on machine at home | No — uses a server you already have | No | +| **Multiple speakers** | Easy — one instance for all LAN speakers | Yes — one instance, managed remotely | One install may serve multiple speakers if port 8000 is LAN-accessible (firmware-dependent; older devices may bind loopback only) | +| **Speaker migration** | Via the AfterTouch web UI | Via `soundtouch-cli` on your local machine | Via SSH into the speaker | +| **HTTPS needed** | No — HTTP on the LAN is fine | **Yes** — speakers require a valid certificate | No | +| **Updates** | Update the host once | Update the server once | SSH into each speaker | +| **Good for** | Most households; want a central dashboard | No always-on home machine; already have a VPS | Single-speaker; no extra hardware at all | --- @@ -24,11 +24,11 @@ three ways to run it — pick the one that fits your situation. Run AfterTouch on a machine already on your home network. The speaker is pointed at it via a simple URL change — nothing else on the speaker is modified. -| | Link | -|--|------| -| **User-friendly walkthrough** | [External Host Walkthrough](EXTERNAL-HOST-WALKTHROUGH.md) — install → discover → migrate → presets | -| **Raspberry Pi quick-install** | [Raspberry Pi Guide](RASPBERRY-PI.md) — one-command installer, systemd integration | -| **Technical reference** | [Deployment Guide](DEPLOYMENT.md) — Docker, Kubernetes, systemd unit, configuration | +| | Link | +|--------------------------------|----------------------------------------------------------------------------------------------------| +| **User-friendly walkthrough** | [External Host Walkthrough](EXTERNAL-HOST-WALKTHROUGH.md) — install → discover → migrate → presets | +| **Raspberry Pi quick-install** | [Raspberry Pi Guide](RASPBERRY-PI.md) — one-command installer, systemd integration | +| **Technical reference** | [Deployment Guide](DEPLOYMENT.md) — Docker, Kubernetes, systemd unit, configuration | --- @@ -39,11 +39,11 @@ speaker migration is done with `soundtouch-cli` from your local machine, and HTT a real certificate is required. Read the security notes in the walkthrough before exposing AfterTouch to the internet. -| | Link | -|--|------| -| **User-friendly walkthrough** | [Cloud Deploy Walkthrough](CLOUD-DEPLOY-WALKTHROUGH.md) — VPS setup, CLI migration, TuneIn gotcha | -| **Technical reference** | [Deployment Guide](DEPLOYMENT.md) — Docker Compose, environment variables, reverse proxy | -| **Community field report** | [discussion #295](https://github.com/gesellix/Bose-SoundTouch/discussions/295) — Hetzner + Coolify setup by wimdeblauwe | +| | Link | +|-------------------------------|-------------------------------------------------------------------------------------------------------------------------| +| **User-friendly walkthrough** | [Cloud Deploy Walkthrough](CLOUD-DEPLOY-WALKTHROUGH.md) — VPS setup, CLI migration, TuneIn gotcha | +| **Technical reference** | [Deployment Guide](DEPLOYMENT.md) — Docker Compose, environment variables, reverse proxy | +| **Community field report** | [discussion #295](https://github.com/gesellix/Bose-SoundTouch/discussions/295) — Hetzner + Coolify setup by wimdeblauwe | --- @@ -53,10 +53,10 @@ AfterTouch runs on the SoundTouch speaker itself. Requires one SSH session to in after that, the speaker self-hosts its own AfterTouch. Delivers the **complete AfterTouch feature set** without any extra hardware. -| | Link | -|--|------| +| | Link | +|-------------------------------|---------------------------------------------------------------------------------------------------------------------------| | **User-friendly walkthrough** | [On-Device Install Walkthrough](ON-DEVICE-INSTALL-WALKTHROUGH.md) — SSH connection through verified radio preset playback | -| **Installer reference** | [On-Device Installer README](../../scripts/on-device-install/README.md) — flags, paths, VERSION override, update/rollback | +| **Installer reference** | [On-Device Installer README](../../scripts/on-device-install/README.md) — flags, paths, VERSION override, update/rollback | --- diff --git a/docs/guides/EXTERNAL-HOST-WALKTHROUGH.md b/docs/guides/EXTERNAL-HOST-WALKTHROUGH.md index 5fdb306..ac9b8b7 100644 --- a/docs/guides/EXTERNAL-HOST-WALKTHROUGH.md +++ b/docs/guides/EXTERNAL-HOST-WALKTHROUGH.md @@ -130,11 +130,11 @@ turn green in the Devices tab. 2. Click **Run health checks** (or wait for them to run automatically). 3. Look for any warnings. The most common after a fresh migration: - | Warning | QuickFix action | - |---------|----------------| - | *Speaker reports an empty ``* | Click **Pair account** / **Apply QuickFix** and confirm. The speaker will reboot. | - | *INTERNET_RADIO source is a stale stub* | Click **Remove INTERNET_RADIO source**. | - | *TuneIn / Radio Browser missing from sources* | These appear automatically once the speaker has paired; if still missing after a QuickFix reboot, trigger discovery again. | + | Warning | QuickFix action | + |-------------------------------------------------|----------------------------------------------------------------------------------------------------------------------------| + | *Speaker reports an empty ``* | Click **Pair account** / **Apply QuickFix** and confirm. The speaker will reboot. | + | *INTERNET_RADIO source is a stale stub* | Click **Remove INTERNET_RADIO source**. | + | *TuneIn / Radio Browser missing from sources* | These appear automatically once the speaker has paired; if still missing after a QuickFix reboot, trigger discovery again. | 4. After any QuickFix that reboots the speaker, re-run the health checks to confirm the warning is gone. @@ -232,14 +232,14 @@ curl -s http://:8000/health | grep version ## Troubleshooting -| Symptom | First check | -|---------|------------| -| Speaker not appearing in Devices | Click **Trigger Discovery**; try adding the IP manually | -| Migration fails | Confirm the speaker can reach `http://:8000` — try `curl http://:8000` from the speaker's SSH shell | -| `margeAccountUUID` still empty after QuickFix + reboot | Re-run Health QuickFix, reboot again | -| Radio source error 1005 | `margeAccountUUID` is empty — complete Step 5 first | -| Speaker reverts to Bose cloud after router restart | Your router's DNS is overriding AfterTouch's server URL — see [MIGRATION-GUIDE.md](MIGRATION-GUIDE.md) for DNS-interception setup | -| Admin UI not reachable | Check `systemctl status soundtouch-service` and firewall rules for port 8000 | +| Symptom | First check | +|--------------------------------------------------------|-----------------------------------------------------------------------------------------------------------------------------------| +| Speaker not appearing in Devices | Click **Trigger Discovery**; try adding the IP manually | +| Migration fails | Confirm the speaker can reach `http://:8000` — try `curl http://:8000` from the speaker's SSH shell | +| `margeAccountUUID` still empty after QuickFix + reboot | Re-run Health QuickFix, reboot again | +| Radio source error 1005 | `margeAccountUUID` is empty — complete Step 5 first | +| Speaker reverts to Bose cloud after router restart | Your router's DNS is overriding AfterTouch's server URL — see [MIGRATION-GUIDE.md](MIGRATION-GUIDE.md) for DNS-interception setup | +| Admin UI not reachable | Check `systemctl status soundtouch-service` and firewall rules for port 8000 | For more detail see [TROUBLESHOOTING.md](TROUBLESHOOTING.md) and [MIGRATION-GUIDE.md](MIGRATION-GUIDE.md). diff --git a/docs/guides/ON-DEVICE-INSTALL-WALKTHROUGH.md b/docs/guides/ON-DEVICE-INSTALL-WALKTHROUGH.md index 8c5ab15..71da29a 100644 --- a/docs/guides/ON-DEVICE-INSTALL-WALKTHROUGH.md +++ b/docs/guides/ON-DEVICE-INSTALL-WALKTHROUGH.md @@ -282,14 +282,14 @@ should start playing the corresponding stream. ## Troubleshooting -| Symptom | First check | -|---------|------------| -| SSH "no matching host key type" | Add `-oHostKeyAlgorithms=+ssh-rsa` | -| Port 8000 not reachable from LAN | Use the SSH tunnel (Step 5) | -| `margeAccountUUID` still empty after reboot | Re-run Health QuickFix, reboot again | -| Radio source error 1005 | `margeAccountUUID` is empty — complete Step 6 first | -| `http://localhost:8000` not responding after install | `logread \| grep aftertouch \| tail -20` | -| No space left on device during install | Run the cleanup in Step 2; check `df -h /mnt/nv` | +| Symptom | First check | +|------------------------------------------------------|-----------------------------------------------------| +| SSH "no matching host key type" | Add `-oHostKeyAlgorithms=+ssh-rsa` | +| Port 8000 not reachable from LAN | Use the SSH tunnel (Step 5) | +| `margeAccountUUID` still empty after reboot | Re-run Health QuickFix, reboot again | +| Radio source error 1005 | `margeAccountUUID` is empty — complete Step 6 first | +| `http://localhost:8000` not responding after install | `logread \| grep aftertouch \| tail -20` | +| No space left on device during install | Run the cleanup in Step 2; check `df -h /mnt/nv` | For more detail on any of these, see [TROUBLESHOOTING.md](./TROUBLESHOOTING.md) and the