6.3 KiB
title
| title |
|---|
| Raspberry Pi Installation Guide |
How to install and manage AfterTouch on a Raspberry Pi (or any always-on Linux host) using the provided installer scripts.
Two scripts are available, one per binary:
| Script | Binary | Role | Default port |
|---|---|---|---|
install.sh |
soundtouch-service |
Cloud-replacement relay — always-on | 80 / 443 |
install-web.sh |
soundtouch-web |
Browser control panel | 8080 |
Both auto-detect CPU architecture (armv7 / arm64 / amd64), create a soundtouch
system user, and install a systemd unit. They are safe to re-run for updates.
For a complete install-through-migration walkthrough see EXTERNAL-HOST-WALKTHROUGH.md. Not sure whether to use a Pi or run AfterTouch on the speaker itself? See DEPLOYMENT-OVERVIEW.md.
soundtouch-service
Installation
curl -fsSL -o install.sh \
https://raw.githubusercontent.com/gesellix/Bose-SoundTouch/main/scripts/raspberry-pi/install.sh
sudo bash install.sh
Install a specific version:
sudo bash install.sh v0.107.0
Override defaults at install time:
sudo \
VERSION=v0.107.0 \
HOSTNAME_FQDN=soundtouch.local \
HTTP_PORT=80 \
HTTPS_PORT=443 \
bash install.sh
Configuration
/etc/soundtouch-service/soundtouch-service.env
Example:
PORT=80
HTTPS_PORT=443
DATA_DIR=/var/lib/soundtouch-service
LOG_PROXY_BODY=false
REDACT_PROXY_LOGS=true
RECORD_INTERACTIONS=true
DISCOVERY_INTERVAL=5m
SERVER_URL=http://soundtouch.local
HTTPS_SERVER_URL=https://soundtouch.local
After editing the env file:
sudo systemctl restart soundtouch-service
Service management
systemctl status soundtouch-service
sudo systemctl enable soundtouch-service # start on boot
sudo systemctl disable soundtouch-service
sudo systemctl stop soundtouch-service
sudo systemctl start soundtouch-service
sudo systemctl restart soundtouch-service
Logs
journalctl -u soundtouch-service -e --no-pager # recent
journalctl -u soundtouch-service -f # follow live
journalctl -u soundtouch-service -b # this boot only
Updates
sudo bash install.sh # update to latest release
sudo bash install.sh v0.107.0 # update to a specific version
The script stops the service, downloads the new binary (backs up the old one to
.old), and restarts automatically. Your env file and data directory are preserved.
Removal
sudo systemctl disable --now soundtouch-service
sudo rm /etc/systemd/system/soundtouch-service.service
sudo rm -rf /etc/soundtouch-service
sudo rm -rf /var/lib/soundtouch-service
sudo rm /usr/local/bin/soundtouch-service
sudo systemctl daemon-reload
soundtouch-web
soundtouch-web is a stateless browser control panel — it holds no persistent
data and can be stopped or restarted at any time without data loss.
Installation
curl -fsSL -o install-web.sh \
https://raw.githubusercontent.com/gesellix/Bose-SoundTouch/main/scripts/raspberry-pi/install-web.sh
sudo bash install-web.sh
Install a specific version:
sudo bash install-web.sh v0.107.0
Override defaults at install time:
sudo \
VERSION=v0.107.0 \
HTTP_PORT=8081 \
bash install-web.sh
Once running, open http://<pi-ip>:8080 in a browser.
Configuration
/etc/soundtouch-web/soundtouch-web.env
Example:
PORT=8080
BIND_ADDR=
DISCOVERY_INTERFACE=
SOUNDTOUCH_DEVICES=
SERVICE_URL=
SERVICE_CA=
SOUNDTOUCH_DEVICES accepts a comma-separated list of IP addresses for manual
device registration — useful when mDNS auto-discovery is unreliable on your
network:
SOUNDTOUCH_DEVICES=192.0.2.1,192.0.2.2
SERVICE_URL links soundtouch-web to your soundtouch-service instance,
which is required for Text-to-Speech ("Speak"). When the service is served
over HTTPS with its own self-signed certificate (the default), also set
SERVICE_CA to that CA certificate, or the proxied TTS call fails with
x509: certificate signed by unknown authority. The CA is the service's
<dataDir>/certs/ca.crt (also downloadable from GET /setup/ca.crt). For
example:
SERVICE_URL=https://soundtouch.local
SERVICE_CA=/var/lib/soundtouch-service/certs/ca.crt
With a plain http:// SERVICE_URL, SERVICE_CA is unused (no TLS) and can
be left empty.
After editing the env file:
sudo systemctl restart soundtouch-web
Port conflicts
Port 8080 is a common default for other services. To check what is already using it:
sudo ss -tulpn | grep :8080
To use a different port, pass HTTP_PORT=<port> to the installer, or edit
the env file after installation and restart the service.
Service management
systemctl status soundtouch-web
sudo systemctl enable soundtouch-web # start on boot
sudo systemctl disable soundtouch-web
sudo systemctl stop soundtouch-web
sudo systemctl start soundtouch-web
sudo systemctl restart soundtouch-web
Logs
journalctl -u soundtouch-web -e --no-pager
journalctl -u soundtouch-web -f
Updates
sudo bash install-web.sh # update to latest release
sudo bash install-web.sh v0.107.0 # update to a specific version
Removal
sudo systemctl disable --now soundtouch-web
sudo rm /etc/systemd/system/soundtouch-web.service
sudo rm -rf /etc/soundtouch-web
sudo rm /usr/local/bin/soundtouch-web
sudo systemctl daemon-reload
Architecture auto-detection
Both installers detect the CPU and pick the matching release asset automatically:
uname -m |
asset suffix |
|---|---|
aarch64 |
linux-arm64 |
armv7l / armv6l |
linux-armv7 |
x86_64 |
linux-amd64 |
Override if needed:
sudo ARCH_ASSET=linux-arm64 bash install.sh
sudo ARCH_ASSET=linux-arm64 bash install-web.sh
Security
Both services run as the soundtouch system user (no login shell, no home
directory). soundtouch-service additionally uses
AmbientCapabilities=CAP_NET_BIND_SERVICE to bind ports 80 / 443 without root.