mirror of
https://github.com/gesellix/Bose-SoundTouch.git
synced 2026-08-19 00:56:16 +00:00
docs: fix on-device multi-speaker claim in deployment overview
'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 <noreply@anthropic.com>
This commit is contained in:
Tobias Gesellchen
co-authored by
Claude Sonnet 4.6
Claude Sonnet 4.6
parent
b05043e6ad
commit
f1f2f260b9
@@ -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 `<margeAccountUUID>`* | 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).
|
||||
|
||||
@@ -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 |
|
||||
|
||||
---
|
||||
|
||||
|
||||
@@ -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 `<margeAccountUUID>`* | 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 `<margeAccountUUID>`* | 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://<host-ip>: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://<host-ip>:8000` — try `curl http://<host-ip>: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://<host-ip>:8000` — try `curl http://<host-ip>: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).
|
||||
|
||||
@@ -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
|
||||
|
||||
Reference in New Issue
Block a user