mirror of https://github.com/gesellix/Bose-SoundTouch.git synced 2026-08-18 08:36:13 +00:00

Files

T

Tobias GesellchenandClaude Sonnet 4.6 56462d7145 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>

2026-05-24 11:31:16 +02:00

2.3 KiB

Raw Blame History

Raspberry Pi Installation Guide

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. Not sure whether to use a Pi or run AfterTouch on the speaker itself? See DEPLOYMENT-OVERVIEW.md.

Automated Installer

We provide a specialized installer script located in the scripts/raspberry-pi/ directory of the repository.

Features

Automatic start on boot: Installs a systemd unit.
Non-root operation: Uses AmbientCapabilities to bind to ports 80/443 without root privileges.
Arch Detection: Automatically selects the correct binary for armv7, arm64, or amd64.
Easy Updates: Re-running the script updates the binary to the latest version.

Installation Steps

Download the installer:

curl -fsSL -o install.sh https://raw.githubusercontent.com/gesellix/bose-soundtouch/main/scripts/raspberry-pi/install.sh

Run with sudo:
```
sudo bash install.sh
```

Overriding Defaults

You can customize the installation using environment variables:

sudo \
  VERSION=v0.92.0 \
  HOSTNAME_FQDN=soundtouch.local \
  HTTP_PORT=80 \
  HTTPS_PORT=443 \
  bash install.sh

Updating the Service

To update the service to a specific version, run the installer with the version as an argument:

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.

Management

Once installed, use standard systemctl commands to manage the service:

# Check status
systemctl status soundtouch-service

# Follow logs
journalctl -u soundtouch-service -f

# Restart
sudo systemctl restart soundtouch-service

Configuration

Configuration is stored in /etc/soundtouch-service/soundtouch-service.env. Note that settings saved via the Web UI (in settings.json) will take precedence over these environment variables once the service is running.

For more details, see the scripts/raspberry-pi/README.md in the repository.

2.3 KiB Raw Blame History