mirror of
https://github.com/gesellix/Bose-SoundTouch.git
synced 2026-08-14 06:36:15 +00:00
docs: reorganize deployment docs — overview page, two walkthroughs, architecture dir
Problem: the existing docs gave no clear path for non-technical users. - GETTING-STARTED.md is a Go library developer guide - RASPBERRY-PI.md stops after the service is running (no migration or preset steps) - DEVICE-LOCAL-INSTALL.md is an architectural analysis that confused installation intent - No single page helped a user choose between external-host vs on-device Changes: - docs/DEVICE-LOCAL-INSTALL.md → docs/architecture/DEVICE-LOCAL-INSTALL.md Move the planning/architecture doc out of the user-visible guides root; add a redirect banner pointing to the user guides - docs/guides/DEPLOYMENT-OVERVIEW.md (new) Navigation landing page: comparison table (external host vs on-device), links to user-friendly walkthrough + technical reference for each scenario - docs/guides/EXTERNAL-HOST-WALKTHROUGH.md (new) Step-by-step for Raspberry Pi / any always-on host: install, discover speaker, run migration wizard, Health QuickFix, verify pairing, set presets via UI or CLI — the post-install steps that RASPBERRY-PI.md did not cover - docs/guides/RASPBERRY-PI.md: cross-link to full walkthrough and overview - README.md: replace the one-liner "see On-Device Installer" with a pointer to the Deployment Overview so both paths are equally visible 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
73d0d4b176
commit
56462d7145
@@ -23,7 +23,7 @@ See the [Survival Guide](https://gesellix.github.io/Bose-SoundTouch/guides/SURVI
|
||||
|
||||
A local server that replaces the Bose cloud ("AfterTouch"). Once your speaker is redirected to it, you have full control without any Bose cloud dependency. The built-in web UI at `http://localhost:8000` handles all setup — no config files needed to get started.
|
||||
|
||||
If you don't want to run a server for this - no problem. The service is small enough to run on the SoundTouch itself. See the [On-Device Installer](./scripts/on-device-install/README.md) for instructions.
|
||||
Not sure which approach fits your situation? See the [Deployment Overview](./docs/guides/DEPLOYMENT-OVERVIEW.md) — it compares running AfterTouch on a Raspberry Pi or other always-on host against running it directly on the SoundTouch speaker, with links to step-by-step walkthroughs for each path.
|
||||
|
||||
**Two scenarios:**
|
||||
|
||||
|
||||
@@ -1,5 +1,15 @@
|
||||
# Device-Local Install: Four User Journeys
|
||||
|
||||
> **Looking for how to actually install AfterTouch?**
|
||||
> See the [Deployment Overview](../guides/DEPLOYMENT-OVERVIEW.md) for user-friendly
|
||||
> step-by-step guides for both deployment scenarios (external host and on-device).
|
||||
>
|
||||
> This document is an **architectural analysis** — user journeys, install patterns,
|
||||
> technology tradeoffs, and future directions. It is aimed at contributors and
|
||||
> project planning, not at end users.
|
||||
|
||||
---
|
||||
|
||||
A user-journey-shaped view of where AfterTouch sits today and where it could go. The same speaker, the same constraints, but four different audiences with non-overlapping needs:
|
||||
|
||||
1. **Initial setup / install** — getting AfterTouch onto a fresh or freshly-orphaned speaker.
|
||||
@@ -0,0 +1,66 @@
|
||||
# AfterTouch Deployment Overview
|
||||
|
||||
AfterTouch replaces the Bose SoundTouch cloud, which shut down on 2026-05-06. There are two
|
||||
ways to run it — pick the one that fits your situation.
|
||||
|
||||
---
|
||||
|
||||
## Which deployment is right for me?
|
||||
|
||||
| | External host | On-device |
|
||||
|--|---------------|-----------|
|
||||
| **What it means** | AfterTouch runs on a separate computer (Raspberry Pi, NAS, PC) on your LAN. Speakers are pointed at that host. | AfterTouch runs directly on the SoundTouch speaker itself. No extra hardware. |
|
||||
| **Extra hardware needed** | Yes — a Raspberry Pi or any always-on machine | No |
|
||||
| **Multiple speakers** | Easy — one instance serves all speakers on the LAN | Each speaker needs its own install |
|
||||
| **Invasiveness** | Low — only the speaker's server-URL config changes | Slightly higher — writes to the speaker's persistent storage |
|
||||
| **Updates** | Update the host; speakers pick it up automatically | SSH into each speaker to update |
|
||||
| **Good for** | Households with several speakers; users who want a central dashboard | Single-speaker households; users who don't have an always-on computer |
|
||||
|
||||
---
|
||||
|
||||
## Option A — External host (Raspberry Pi, NAS, PC)
|
||||
|
||||
The speaker stays unmodified. You run AfterTouch on a machine you already have
|
||||
on your home network, then tell the speaker to use it instead of the Bose cloud.
|
||||
|
||||
| | Link |
|
||||
|--|------|
|
||||
| **User-friendly walkthrough** | [External Host Walkthrough](EXTERNAL-HOST-WALKTHROUGH.md) — step-by-step from install through preset setup |
|
||||
| **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 |
|
||||
|
||||
---
|
||||
|
||||
## Option B — On-device (AfterTouch on the speaker)
|
||||
|
||||
AfterTouch runs on the SoundTouch speaker itself. Requires one SSH session to
|
||||
install; after that, the speaker self-hosts its own AfterTouch.
|
||||
|
||||
| | 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 |
|
||||
|
||||
---
|
||||
|
||||
## After choosing a deployment path
|
||||
|
||||
Once AfterTouch is running and your speaker is migrated, the next steps are the
|
||||
same regardless of which deployment you chose:
|
||||
|
||||
- **Health tab** — open the AfterTouch UI → Health, and run any QuickFixes shown
|
||||
(especially *"empty margeAccountUUID"* if present).
|
||||
- **Music sources** — the Health tab also shows whether Internet Radio, TuneIn,
|
||||
and Radio Browser are active.
|
||||
- **Presets** — use the AfterTouch web UI or `soundtouch-cli preset store-current`
|
||||
to program the physical preset buttons.
|
||||
|
||||
For troubleshooting either deployment see [TROUBLESHOOTING.md](TROUBLESHOOTING.md).
|
||||
|
||||
---
|
||||
|
||||
## Architecture and planning documents
|
||||
|
||||
If you're a contributor or interested in the technical design decisions
|
||||
(install patterns, user journeys, Gio/Wails tradeoffs, mini-build discussion),
|
||||
see [docs/architecture/DEVICE-LOCAL-INSTALL.md](../architecture/DEVICE-LOCAL-INSTALL.md).
|
||||
@@ -0,0 +1,245 @@
|
||||
# External Host Walkthrough
|
||||
|
||||
A step-by-step guide to running AfterTouch on a Raspberry Pi (or any always-on
|
||||
computer) and migrating your Bose SoundTouch speakers to use it.
|
||||
|
||||
By the end you'll have AfterTouch running on your host, your speaker(s) pointed
|
||||
at it, and your radio presets working again.
|
||||
|
||||
For a comparison with the on-device install option see
|
||||
[DEPLOYMENT-OVERVIEW.md](DEPLOYMENT-OVERVIEW.md).
|
||||
|
||||
---
|
||||
|
||||
## What you need
|
||||
|
||||
- A **Raspberry Pi** (Zero 2W, 3, or 4), a NAS, or any always-on Linux/macOS/Windows
|
||||
machine on your home network.
|
||||
- Your **Bose SoundTouch speaker** on the same network. It doesn't need SSH enabled.
|
||||
- A **browser** on any device on the same network.
|
||||
- The **speaker's LAN IP address** — find it in your router's device list, or run
|
||||
`arp -a` on your computer. Replace `192.0.2.1` throughout with the real IP.
|
||||
|
||||
---
|
||||
|
||||
## Step 1 — Install AfterTouch on your host
|
||||
|
||||
### Raspberry Pi (recommended for always-on use)
|
||||
|
||||
```bash
|
||||
curl -fsSL -o install.sh \
|
||||
https://raw.githubusercontent.com/gesellix/bose-soundtouch/main/scripts/raspberry-pi/install.sh
|
||||
sudo bash install.sh
|
||||
```
|
||||
|
||||
The installer detects your Pi's architecture (armv7, arm64, or amd64), downloads
|
||||
the binary, creates a `soundtouch` system user, and registers a systemd unit that
|
||||
starts on boot.
|
||||
|
||||
To install a specific version:
|
||||
|
||||
```bash
|
||||
sudo bash install.sh v0.92.0
|
||||
```
|
||||
|
||||
Check that the service is running:
|
||||
|
||||
```bash
|
||||
systemctl status soundtouch-service
|
||||
```
|
||||
|
||||
The Admin UI is now at **`http://<pi-ip>:8000`** — open it in a browser.
|
||||
|
||||
### Other Linux hosts (systemd)
|
||||
|
||||
Download the binary for your architecture from the
|
||||
[Releases page](https://github.com/gesellix/Bose-SoundTouch/releases), then
|
||||
install it as a systemd service — see [DEPLOYMENT.md](DEPLOYMENT.md) for the
|
||||
unit file template.
|
||||
|
||||
### Docker
|
||||
|
||||
```bash
|
||||
docker run -d \
|
||||
--name aftertouch \
|
||||
--network host \
|
||||
-e SERVER_URL=http://192.0.2.10:8000 \
|
||||
-v aftertouch-data:/data \
|
||||
ghcr.io/gesellix/bose-soundtouch:latest
|
||||
```
|
||||
|
||||
Replace `192.0.2.10` with the host machine's LAN IP. The `--network host` flag
|
||||
is required so AfterTouch can reach the speakers and respond to mDNS discovery.
|
||||
|
||||
---
|
||||
|
||||
## Step 2 — Note your host's LAN IP and open the Admin UI
|
||||
|
||||
Your host's LAN IP is the address your speakers will use to reach AfterTouch.
|
||||
Find it with:
|
||||
|
||||
```bash
|
||||
# Linux / macOS
|
||||
ip addr show # or: hostname -I
|
||||
# Windows
|
||||
ipconfig
|
||||
```
|
||||
|
||||
Open **`http://<host-ip>:8000`** in a browser. You should see the AfterTouch
|
||||
Admin UI. If it's not reachable, check that port 8000 is not blocked by a
|
||||
firewall on the host.
|
||||
|
||||
---
|
||||
|
||||
## Step 3 — Discover your speaker
|
||||
|
||||
In the Admin UI:
|
||||
|
||||
1. Go to the **Devices** tab. AfterTouch runs mDNS discovery automatically —
|
||||
your speaker should appear within a minute or two.
|
||||
2. If it doesn't appear, click **Trigger Discovery**. If it still doesn't appear,
|
||||
add it manually: enter `192.0.2.1` (your speaker's IP) and click **Add**.
|
||||
|
||||
You should now see your speaker listed with its name and model.
|
||||
|
||||
---
|
||||
|
||||
## Step 4 — Migrate the speaker
|
||||
|
||||
This step tells the speaker to use your AfterTouch instance instead of the
|
||||
defunct Bose cloud. **The speaker gets a new server URL written to it; this is
|
||||
reversible via the "Revert" button.**
|
||||
|
||||
1. Click your speaker in the Devices list.
|
||||
2. Click **Migrate** (or open the Migration wizard from the speaker's detail page).
|
||||
3. The wizard shows a summary of what will change. Review it and click **Confirm**.
|
||||
4. AfterTouch rewrites the speaker's server-URL config and reboots it.
|
||||
5. Wait 2–3 minutes for the speaker to come back up.
|
||||
|
||||
After the reboot the speaker reconnects to AfterTouch. You should see its status
|
||||
turn green in the Devices tab.
|
||||
|
||||
> **If the migration wizard asks for your AfterTouch URL**, enter
|
||||
> `http://<host-ip>:8000` (the same URL you used to open the Admin UI).
|
||||
|
||||
---
|
||||
|
||||
## Step 5 — Check the Health tab and run QuickFixes
|
||||
|
||||
1. Click your speaker in the Devices list, then open the **Health** 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. |
|
||||
|
||||
4. After any QuickFix that reboots the speaker, re-run the health checks to
|
||||
confirm the warning is gone.
|
||||
|
||||
---
|
||||
|
||||
## Step 6 — Verify pairing and sources
|
||||
|
||||
After the health checks are green, confirm from your browser:
|
||||
|
||||
- In the **Devices** tab, click the speaker. Its **Account** field should show
|
||||
a non-empty UUID, not `default`.
|
||||
- In the **Sources** tab (if present), or via the health checks, confirm
|
||||
`LOCAL_INTERNET_RADIO`, `TUNEIN`, and `RADIO_BROWSER` are listed.
|
||||
|
||||
You can also check directly from any machine on the LAN:
|
||||
|
||||
```bash
|
||||
# Replace 192.0.2.1 with your speaker's IP
|
||||
curl -s http://192.0.2.1:8090/info | grep -i marge
|
||||
curl -s http://192.0.2.1:8090/sources
|
||||
```
|
||||
|
||||
`margeAccountUUID` must not be empty. Sources should include
|
||||
`LOCAL_INTERNET_RADIO`, `TUNEIN`, and `RADIO_BROWSER`.
|
||||
|
||||
---
|
||||
|
||||
## Step 7 — Set up preset buttons (optional)
|
||||
|
||||
### Via the AfterTouch web UI
|
||||
|
||||
1. Open **`http://<host-ip>:8000`** and navigate to your speaker.
|
||||
2. Use the **Radio Browser** or **TuneIn** tab to find a station.
|
||||
3. Click the station to play it.
|
||||
4. Click **Store as preset → slot 1** (or whichever slot you want).
|
||||
5. Repeat for slots 2–6.
|
||||
|
||||
### Via soundtouch-cli (any machine on the LAN)
|
||||
|
||||
Download the CLI for your machine from the
|
||||
[Releases page](https://github.com/gesellix/Bose-SoundTouch/releases), then:
|
||||
|
||||
```bash
|
||||
# Play a custom radio stream on the speaker
|
||||
soundtouch-cli --host 192.0.2.1 source custom-radio \
|
||||
--url "https://stream.laut.fm/country-nonstop" \
|
||||
--name "Country Nonstop" \
|
||||
--service-url "http://<host-ip>:8000"
|
||||
sleep 5
|
||||
|
||||
# Store it to preset slot 1
|
||||
soundtouch-cli --host 192.0.2.1 preset store-current --slot 1
|
||||
```
|
||||
|
||||
Repeat for each slot. See the
|
||||
[On-Device Install Walkthrough](ON-DEVICE-INSTALL-WALKTHROUGH.md#step-9--store-custom-radio-streams-to-preset-buttons)
|
||||
for six worked examples with Austrian internet radio stations.
|
||||
|
||||
---
|
||||
|
||||
## Step 8 — Verify and enjoy
|
||||
|
||||
Press a preset button on the speaker briefly (a long press overwrites the preset).
|
||||
Each slot should play the corresponding stream.
|
||||
|
||||
To check what's stored:
|
||||
|
||||
```bash
|
||||
curl -s http://192.0.2.1:8090/presets
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Updating AfterTouch
|
||||
|
||||
### Raspberry Pi
|
||||
|
||||
```bash
|
||||
sudo bash install.sh # updates to latest release
|
||||
sudo bash install.sh v0.93.0 # updates to a specific version
|
||||
```
|
||||
|
||||
The installer stops the service, downloads the new binary, and restarts
|
||||
automatically.
|
||||
|
||||
### Checking current version
|
||||
|
||||
```bash
|
||||
systemctl status soundtouch-service # shows the running version in the log
|
||||
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 |
|
||||
|
||||
For more detail see [TROUBLESHOOTING.md](TROUBLESHOOTING.md) and
|
||||
[MIGRATION-GUIDE.md](MIGRATION-GUIDE.md).
|
||||
@@ -2,6 +2,11 @@
|
||||
|
||||
This guide explains how to install the `soundtouch-service` as a persistent systemd service on a Raspberry Pi (tested on Raspberry Pi Zero 2W, 3, and 4).
|
||||
|
||||
For a complete walkthrough — from install through speaker migration and preset setup — see
|
||||
[EXTERNAL-HOST-WALKTHROUGH.md](EXTERNAL-HOST-WALKTHROUGH.md).
|
||||
Not sure whether to use a Pi or run AfterTouch on the speaker itself? See
|
||||
[DEPLOYMENT-OVERVIEW.md](DEPLOYMENT-OVERVIEW.md).
|
||||
|
||||
## Automated Installer
|
||||
|
||||
We provide a specialized installer script located in the `scripts/raspberry-pi/` directory of the repository.
|
||||
@@ -30,7 +35,7 @@ You can customize the installation using environment variables:
|
||||
|
||||
```bash
|
||||
sudo \
|
||||
VERSION=v0.17.0 \
|
||||
VERSION=v0.92.0 \
|
||||
HOSTNAME_FQDN=soundtouch.local \
|
||||
HTTP_PORT=80 \
|
||||
HTTPS_PORT=443 \
|
||||
@@ -42,7 +47,7 @@ sudo \
|
||||
To update the service to a specific version, run the installer with the version as an argument:
|
||||
|
||||
```bash
|
||||
sudo bash install.sh v0.18.1
|
||||
sudo bash install.sh v0.92.0
|
||||
```
|
||||
|
||||
The installer will automatically fetch the latest version of itself for that release and then update the service binary and restart it.
|
||||
|
||||
Reference in New Issue
Block a user