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-player`	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-player

soundtouch-player 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-player/soundtouch-player.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-player 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-player

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-player
sudo systemctl enable soundtouch-player    # start on boot
sudo systemctl disable soundtouch-player
sudo systemctl stop soundtouch-player
sudo systemctl start soundtouch-player
sudo systemctl restart soundtouch-player

Logs

journalctl -u soundtouch-player -e --no-pager
journalctl -u soundtouch-player -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-player
sudo rm /etc/systemd/system/soundtouch-player.service
sudo rm -rf /etc/soundtouch-player
sudo rm /usr/local/bin/soundtouch-player
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.

Last updated on June 9, 2026

Playing Music from a DLNA / NAS Library Self-Hosting AfterTouch