🎉 live server seems to be working now
This commit is contained in:
276
third_party/sendspin-go/docs/superpowers/specs/2026-04-20-server-config-yaml-design.md
vendored
Normal file
276
third_party/sendspin-go/docs/superpowers/specs/2026-04-20-server-config-yaml-design.md
vendored
Normal file
@@ -0,0 +1,276 @@
|
||||
# sendspin-server: YAML config file + daemon mode
|
||||
|
||||
**Status:** Design approved 2026-04-20
|
||||
**Tracks:** parity with `sendspin-player` config (closes equivalent of #40 for the server side)
|
||||
|
||||
## Problem
|
||||
|
||||
`sendspin-server` has no config-file support and no `--daemon` flag. To run it
|
||||
under systemd today, an operator has to stuff every option into `ExecStart` or
|
||||
an env file, and logging fights `journalctl` because the binary always opens
|
||||
`sendspin-server.log`. The player solved this with a three-layer precedence
|
||||
model (CLI > env > YAML > default), `WriteStringKey` for comment-preserving
|
||||
round-trips, and a `--daemon` flag that logs to stdout only. The server should
|
||||
get the same treatment.
|
||||
|
||||
## Goals
|
||||
|
||||
1. YAML config file at `/etc/sendspin/server.yaml` or `~/.config/sendspin/server.yaml` with the same search-order contract as `player.yaml`.
|
||||
2. `SENDSPIN_SERVER_*` env var overlay with the same precedence rules as the player.
|
||||
3. A `--daemon` flag that logs to stdout only (journalctl-friendly) and suppresses both the TUI and the log file.
|
||||
4. `systemctl enable --now sendspin-server` works after `make install-daemon`.
|
||||
5. Zero behavior change for users who don't opt in to any of the above.
|
||||
|
||||
## Non-goals
|
||||
|
||||
- **No write-back.** The server has no analog of the player's `client_id`; mDNS rediscovery handles instance identity at the network layer. `WriteStringKey` stays unused by the server (and stays generic in case future features need it).
|
||||
- **No `-stream-logs` alias.** The player has it for historical reasons; the server starts clean without the redundant alias.
|
||||
- **No unified `ConfigFile` struct.** Each binary keeps its own typed struct. Only the machinery (search paths, flag overlay) is shared.
|
||||
|
||||
## Approach
|
||||
|
||||
Refactor `pkg/sendspin/config.go` so the generic machinery takes a
|
||||
`(envPrefix, map[string]string)` pair instead of a typed `*PlayerConfigFile`,
|
||||
then add a parallel `ServerConfigFile` / `LoadServerConfig` /
|
||||
`DefaultServerConfigPath` surface alongside the player's. The player's
|
||||
`asStringMap()` already produces exactly the map the refactored function
|
||||
needs, so the call-site change is one line.
|
||||
|
||||
No public API outside `pkg/sendspin` uses the old `ApplyEnvAndFile` signature
|
||||
(verified by grep: only `main.go`, `config.go`, and `config_test.go`). The
|
||||
technically-breaking signature change is contained.
|
||||
|
||||
## Architecture
|
||||
|
||||
### `pkg/sendspin/config.go` — refactor
|
||||
|
||||
Change:
|
||||
|
||||
```go
|
||||
// Before
|
||||
func ApplyEnvAndFile(fs *flag.FlagSet, setByUser map[string]bool, cfg *PlayerConfigFile) error
|
||||
|
||||
// After
|
||||
func ApplyEnvAndFile(fs *flag.FlagSet, setByUser map[string]bool, envPrefix string, fileValues map[string]string) error
|
||||
```
|
||||
|
||||
New unexported helpers:
|
||||
|
||||
- `loadYAMLConfig(searchPaths []string, out any) (string, error)` — opens the first existing file, unmarshals into `out`. Missing files are not an error (`(nil, "", nil)` equivalent).
|
||||
- `userConfigPath(relative string) (string, error)` — wraps `os.UserConfigDir() + "/sendspin/" + relative`. Used by both `DefaultPlayerConfigPath` and `DefaultServerConfigPath`.
|
||||
|
||||
Existing public surface (`WriteStringKey`, `topLevelMapping`, `setOrAppendStringKey`, `atomicWriteFile`) is already generic and unchanged.
|
||||
|
||||
### `pkg/sendspin/config.go` — new server surface
|
||||
|
||||
```go
|
||||
const ServerEnvPrefix = "SENDSPIN_SERVER_"
|
||||
|
||||
type ServerConfigFile struct {
|
||||
Name string `yaml:"name,omitempty"`
|
||||
Port *int `yaml:"port,omitempty"`
|
||||
LogFile string `yaml:"log_file,omitempty"`
|
||||
Debug *bool `yaml:"debug,omitempty"`
|
||||
NoMDNS *bool `yaml:"no_mdns,omitempty"`
|
||||
NoTUI *bool `yaml:"no_tui,omitempty"`
|
||||
Audio string `yaml:"audio,omitempty"`
|
||||
DiscoverClients *bool `yaml:"discover_clients,omitempty"`
|
||||
Daemon *bool `yaml:"daemon,omitempty"`
|
||||
}
|
||||
|
||||
func LoadServerConfig(explicitPath string) (*ServerConfigFile, string, error)
|
||||
func DefaultServerConfigPath() (string, error)
|
||||
func (c *ServerConfigFile) asStringMap() map[string]string
|
||||
```
|
||||
|
||||
`LoadServerConfig` search order (first existing wins; missing is not an error):
|
||||
|
||||
1. `explicitPath` if non-empty
|
||||
2. `$SENDSPIN_SERVER_CONFIG`
|
||||
3. `<UserConfigDir>/sendspin/server.yaml`
|
||||
4. `/etc/sendspin/server.yaml`
|
||||
|
||||
### Player call-site update
|
||||
|
||||
```go
|
||||
// main.go (player)
|
||||
if err := sendspin.ApplyEnvAndFile(
|
||||
flag.CommandLine, setByUser, sendspin.PlayerEnvPrefix, cfg.asStringMap(),
|
||||
); err != nil { ... }
|
||||
```
|
||||
|
||||
`cfg.asStringMap()` on a nil `*PlayerConfigFile` must keep returning an empty map (existing behavior — confirmed in `TestApplyEnvAndFile_NilConfigStillHonorsEnv`). Preserve that contract.
|
||||
|
||||
### `cmd/sendspin-server/main.go` — new flags & wiring
|
||||
|
||||
Add:
|
||||
|
||||
```go
|
||||
daemon = flag.Bool("daemon", false, "Daemon mode: log to stdout only (journalctl-friendly), no TUI, no log file")
|
||||
configPath = flag.String("config", "", "Path to server.yaml config file. Default search: $SENDSPIN_SERVER_CONFIG, ~/.config/sendspin/server.yaml, /etc/sendspin/server.yaml.")
|
||||
```
|
||||
|
||||
After `flag.Parse()`:
|
||||
|
||||
```go
|
||||
setByUser := map[string]bool{"config": true}
|
||||
flag.Visit(func(f *flag.Flag) { setByUser[f.Name] = true })
|
||||
|
||||
cfg, _, err := sendspin.LoadServerConfig(*configPath)
|
||||
if err != nil { log.Fatalf("config: %v", err) }
|
||||
if err := sendspin.ApplyEnvAndFile(
|
||||
flag.CommandLine, setByUser, sendspin.ServerEnvPrefix, cfg.asStringMap(),
|
||||
); err != nil { log.Fatalf("config overlay: %v", err) }
|
||||
```
|
||||
|
||||
### Daemon mode
|
||||
|
||||
- `useTUI := !(*noTUI || *daemon)`
|
||||
- Logging branch:
|
||||
- `-daemon` → `log.SetOutput(os.Stdout)`; skip opening `*logFile`.
|
||||
- TUI on → log to file only (unchanged).
|
||||
- Neither → `io.MultiWriter(os.Stdout, f)` (unchanged).
|
||||
- Non-TUI startup banner logs `"Starting Sendspin Server: %s (port %d)"` and, when `-daemon`, adds `"Daemon mode: logging to stdout only"`.
|
||||
|
||||
### Distribution artifacts
|
||||
|
||||
**`dist/systemd/sendspin-server.service`** — shape mirrors `sendspin-player.service`:
|
||||
|
||||
```ini
|
||||
[Unit]
|
||||
Description=Sendspin Server
|
||||
Documentation=https://github.com/Sendspin/sendspin-go
|
||||
After=network-online.target sound.target
|
||||
Wants=network-online.target
|
||||
|
||||
[Service]
|
||||
Type=simple
|
||||
ExecStart=/usr/local/bin/sendspin-server --daemon
|
||||
Restart=on-failure
|
||||
RestartSec=5
|
||||
EnvironmentFile=-/etc/default/sendspin-server
|
||||
ExecStart=
|
||||
ExecStart=/usr/local/bin/sendspin-server --daemon $SENDSPIN_SERVER_OPTS
|
||||
|
||||
NoNewPrivileges=true
|
||||
ProtectSystem=strict
|
||||
ProtectHome=read-only
|
||||
PrivateTmp=true
|
||||
|
||||
[Install]
|
||||
WantedBy=multi-user.target
|
||||
```
|
||||
|
||||
`ProtectHome=read-only` (not `yes`) so `-audio /home/user/Music/...` still works.
|
||||
|
||||
**`dist/systemd/sendspin-server.env`** — operator-editable env file installed to `/etc/default/sendspin-server`:
|
||||
|
||||
```sh
|
||||
# sendspin-server: extra CLI flags appended to ExecStart
|
||||
# Prefer /etc/sendspin/server.yaml for structured config; use this for
|
||||
# ad-hoc overrides or keys that aren't (yet) in the YAML.
|
||||
# SENDSPIN_SERVER_OPTS="--debug --discover-clients"
|
||||
SENDSPIN_SERVER_OPTS=""
|
||||
```
|
||||
|
||||
**`dist/config/server.example.yaml`** — annotated starter, every key commented out so the file is a no-op until edited:
|
||||
|
||||
```yaml
|
||||
# sendspin-server configuration
|
||||
#
|
||||
# Search order (first existing file wins; missing is not an error):
|
||||
# 1. --config <path>
|
||||
# 2. $SENDSPIN_SERVER_CONFIG
|
||||
# 3. ~/.config/sendspin/server.yaml (user install)
|
||||
# 4. /etc/sendspin/server.yaml (daemon / system-wide)
|
||||
#
|
||||
# Per-value precedence for every key below:
|
||||
# CLI flag > SENDSPIN_SERVER_<UPPER_SNAKE> env > this file > built-in default
|
||||
|
||||
# --- Identity ---
|
||||
# name: "Living Room Server"
|
||||
|
||||
# --- Network ---
|
||||
# port: 8927
|
||||
# no_mdns: false
|
||||
# discover_clients: false
|
||||
|
||||
# --- Audio source ---
|
||||
# Local file path, HTTP URL, or HLS URL. Empty = built-in test tone.
|
||||
# audio: "/srv/music/radio.m3u8"
|
||||
|
||||
# --- Logging / runtime ---
|
||||
# daemon: false
|
||||
# no_tui: false
|
||||
# log_file: "sendspin-server.log"
|
||||
# debug: false
|
||||
```
|
||||
|
||||
### Makefile
|
||||
|
||||
Split `install-daemon` / `uninstall-daemon` into leaf + aggregate targets:
|
||||
|
||||
- `install-player-daemon` — existing player install logic, renamed.
|
||||
- `install-server-daemon` — new; installs binary to `/usr/local/bin`, unit file to `/etc/systemd/system`, env file to `/etc/default/sendspin-server`, example YAML to `/etc/sendspin/server.yaml`. Each of the two editable files is installed only if absent (guard pattern from the player).
|
||||
- `install-daemon` — aggregate: `install-player-daemon install-server-daemon`.
|
||||
- `uninstall-server-daemon` — stops/disables unit, removes binary and unit file, leaves `/etc/default/sendspin-server` and `/etc/sendspin/server.yaml` intact.
|
||||
- `uninstall-daemon` — aggregate.
|
||||
|
||||
`clean` already removes `sendspin-server`; no change.
|
||||
|
||||
## Flag → YAML key mapping
|
||||
|
||||
| Flag | YAML key | Type | Default |
|
||||
|---|---|---|---|
|
||||
| `-port` | `port` | `*int` | 8927 |
|
||||
| `-name` | `name` | `string` | `<hostname>-sendspin-server` |
|
||||
| `-log-file` | `log_file` | `string` | `sendspin-server.log` |
|
||||
| `-debug` | `debug` | `*bool` | false |
|
||||
| `-no-mdns` | `no_mdns` | `*bool` | false |
|
||||
| `-no-tui` | `no_tui` | `*bool` | false |
|
||||
| `-audio` | `audio` | `string` | *(empty → test tone)* |
|
||||
| `-discover-clients` | `discover_clients` | `*bool` | false |
|
||||
| `-daemon` | `daemon` | `*bool` | false |
|
||||
| `-config` | *(not in YAML — circular)* | `string` | *(empty)* |
|
||||
|
||||
## Precedence
|
||||
|
||||
For every key: **CLI flag > `SENDSPIN_SERVER_<UPPER_SNAKE>` env > `server.yaml` > built-in default**.
|
||||
|
||||
Matches the player exactly. Enforced by the shared `ApplyEnvAndFile` helper.
|
||||
|
||||
## Error handling
|
||||
|
||||
- Invalid YAML → `log.Fatalf("config: %v", err)` at startup.
|
||||
- Invalid env var (e.g., `SENDSPIN_SERVER_PORT=abc`) → fatal; error message includes the offending flag name. Behavior inherited from the shared helper.
|
||||
- Missing config file → silent no-op; all keys fall through to flag defaults. This is the documented contract.
|
||||
- `-audio` validation stays in `server.NewAudioSource`; config loading only carries the string.
|
||||
- `-daemon` combined with TUI flags → daemon wins, no warning. Matches player behavior.
|
||||
|
||||
## Testing
|
||||
|
||||
**Existing player tests** (`pkg/sendspin/config_test.go`) — each `ApplyEnvAndFile(..., cfg)` call-site must be rewritten to `ApplyEnvAndFile(..., PlayerEnvPrefix, cfg.asStringMap())` to match the new signature. `TestApplyEnvAndFile_NilConfigStillHonorsEnv` passes a nil map instead of a nil struct (a nil `map[string]string` iterates as empty, so the env-only path behaves identically). No assertion changes; the precedence tests then exercise the shared code path for both binaries.
|
||||
|
||||
**New server tests** — structural coverage only:
|
||||
|
||||
- `TestLoadServerConfig_ExplicitPathWithAllKeys` — round-trip every `ServerConfigFile` field through YAML.
|
||||
- `TestLoadServerConfig_MissingFileIsNotAnError` — contract symmetry.
|
||||
- `TestLoadServerConfig_EnvPathHonored` — `SENDSPIN_SERVER_CONFIG` picked up.
|
||||
- `TestApplyEnvAndFile_ServerEnvPrefix` — confirms the generalized `envPrefix` parameter routes `SENDSPIN_SERVER_*` correctly.
|
||||
|
||||
No new `WriteStringKey` tests (server doesn't use write-back).
|
||||
|
||||
## Manual verification (part of the plan's completion step)
|
||||
|
||||
1. `sendspin-server` with no config file → unchanged behavior.
|
||||
2. `sendspin-server --config /tmp/s.yaml` with `port: 9000` → binds 9000.
|
||||
3. `SENDSPIN_SERVER_PORT=9001 sendspin-server --config /tmp/s.yaml` → binds 9001 (env beats file).
|
||||
4. `sendspin-server --port 9002 --config /tmp/s.yaml` → binds 9002 (CLI beats env + file).
|
||||
5. `sendspin-server --daemon` → no TUI, stdout logging with timestamps, no `sendspin-server.log` created.
|
||||
6. Linux box: `make install-daemon && systemctl enable --now sendspin-server && journalctl -u sendspin-server -f` → clean startup.
|
||||
|
||||
## Out-of-scope (future work)
|
||||
|
||||
- `server_id` / persistent identity for the server.
|
||||
- A unified `pkg/sendspin/configfile` sub-package if a third binary ever joins (YAGNI until then).
|
||||
- README deep-dive on daemon operation — this work adds a one-line pointer only.
|
||||
97
third_party/sendspin-go/docs/superpowers/specs/2026-05-01-quickstart-pi-design.md
vendored
Normal file
97
third_party/sendspin-go/docs/superpowers/specs/2026-05-01-quickstart-pi-design.md
vendored
Normal file
@@ -0,0 +1,97 @@
|
||||
# sendspin-player: Raspberry Pi quickstart script
|
||||
|
||||
**Status:** Design approved 2026-05-01
|
||||
**Tracks:** lower the on-ramp for Pi-as-player setups using prebuilt arm64 release tarballs
|
||||
|
||||
## Problem
|
||||
|
||||
Setting up a Raspberry Pi as a Sendspin player today requires the user to: install build-time deps via `install-deps.sh`, clone the repo, build with the CGo toolchain, then either run the binary by hand or wire up systemd through `make install-player-daemon`. None of that is friendly for a "stick a Pi behind the speakers and forget about it" workflow, and almost all of it is unnecessary now that the GitHub Releases pipeline ships ready-to-run `linux-arm64` tarballs.
|
||||
|
||||
A `curl | sudo bash` quickstart that takes a fresh 64-bit Raspberry Pi OS install to a running, mDNS-discoverable player in one command closes that gap.
|
||||
|
||||
## Goals
|
||||
|
||||
1. Single-command install: `curl -fsSL https://raw.githubusercontent.com/Sendspin/sendspin-go/main/scripts/quickstart-pi.sh | sudo bash` brings up the player on a fresh 64-bit Raspberry Pi OS — Lite is the recommended target (headless, no PulseAudio/PipeWire, lower scheduling jitter), full desktop also works. Bookworm or newer is required for the `libflac12` runtime package.
|
||||
2. Idempotent re-run: invoking the script a second time upgrades the binary and refreshes the unit file in place.
|
||||
3. Optional one-shot configuration via flags: `bash -s -- --name living-room --device "USB DAC"`.
|
||||
4. Clean uninstall via `--uninstall`.
|
||||
5. Pin a specific version via `--version v1.6.2` (default: latest).
|
||||
6. Zero changes to existing build, daemon-install, or release flows.
|
||||
|
||||
## Non-goals
|
||||
|
||||
- **No 32-bit Pi support.** Releases ship `linux-arm64` only. The script detects `armv6l` / `armv7l` and exits with a clear pointer to 64-bit Raspberry Pi OS. Pi 1 / Zero (v1) / Zero W are excluded by hardware; Pi 2 is excluded by OS choice.
|
||||
- **No non-Debian distros.** The script's package-install step targets `apt-get`. Other distros must follow the README's manual install steps.
|
||||
- **No Debian < 12 (Bullseye and earlier).** The script hard-codes `libflac12`, which is Bookworm's package name. On older Debian / Pi OS, `apt-get install libflac12` fails loudly with "no installation candidate" — that error is acceptable as the user-facing rejection rather than adding fallback logic.
|
||||
- **No checksum / signature verification.** HTTPS to `github.com` is the same trust boundary the `curl | bash` itself crosses; layering a second integrity check adds operational cost without materially changing the threat model. May reconsider if signed releases land later.
|
||||
- **No interactive device picker.** `--device "<exact name>"` is the documented path. Users wanting a list run `sendspin-player --list-audio-devices` after install.
|
||||
- **No support for running `sendspin-server` via this script.** Pi-as-server is a less common configuration; if it becomes one, a sibling script is the right move, not flag bloat in this one.
|
||||
- **No purge of `/etc/sendspin/` on `--uninstall`.** Matches the existing `make uninstall-player-daemon` behavior; user state is precious.
|
||||
|
||||
## Approach
|
||||
|
||||
A single shell script at `scripts/quickstart-pi.sh`, fetched via raw GitHub URL and piped to `sudo bash`. Self-contained: every helper is inlined, no second fetch, no source tree dependency.
|
||||
|
||||
The script reuses every artifact already shipped in the repo:
|
||||
|
||||
- The `dist/systemd/sendspin-player.service` unit (already root-running with `ProtectSystem=strict` / `ProtectHome=read-only` hardening; no change).
|
||||
- The `dist/systemd/sendspin-player.env` file (already wires `SENDSPIN_PLAYER_OPTS` into `ExecStart`).
|
||||
- The `dist/config/player.example.yaml` file (already configured with sensible defaults; the daemon writes its own `client_id` back on first launch).
|
||||
|
||||
These are downloaded directly from `https://raw.githubusercontent.com/Sendspin/sendspin-go/<ref>/dist/...` at the resolved release tag (so a `--version v1.6.2` install gets the unit/config/env files from that tag, not from `main`).
|
||||
|
||||
The release tarball comes from GitHub's `/releases/latest/download/` redirect by default, or `/releases/download/<tag>/` when `--version` is set. No GitHub API call, no JSON parsing.
|
||||
|
||||
`/etc/default/sendspin-player` is touched only on first install OR when `--name` / `--device` are passed on this invocation. That makes "re-run with new flags" the documented reconfigure path; "re-run with no flags" is purely an upgrade.
|
||||
|
||||
## Flow
|
||||
|
||||
The script executes the following stages in order. Any non-zero exit aborts the run; idempotency is the recovery story.
|
||||
|
||||
1. **Argument parse.** `--name <s>`, `--device <s>`, `--version <tag>`, `--uninstall`, `-h|--help`. Unknown flags abort with usage.
|
||||
2. **Pre-flight.**
|
||||
- Effective UID must be 0 (else: print sudo hint, exit).
|
||||
- `uname -m` must be `aarch64` (else: print 64-bit-OS hint, exit).
|
||||
- `/etc/debian_version` must exist (else: point at README manual steps, exit).
|
||||
- `command -v systemctl` must succeed.
|
||||
3. **Uninstall short-circuit.** If `--uninstall` is set:
|
||||
- `systemctl disable --now sendspin-player` (tolerate "no such unit" cleanly).
|
||||
- Remove `/usr/local/bin/sendspin-player` and `/etc/systemd/system/sendspin-player.service`.
|
||||
- `systemctl daemon-reload`.
|
||||
- Print note: "Config preserved at `/etc/sendspin/` and `/etc/default/sendspin-player`. Remove manually for a full purge."
|
||||
- Exit 0.
|
||||
4. **Install runtime deps.** `apt-get update && apt-get install -y libopus0 libopusfile0 libflac12 libasound2 ca-certificates curl tar`. `libasound2` is the ALSA userspace library miniaudio links against; it is usually present on Pi OS Lite but not guaranteed on a truly minimal image, so we install it explicitly.
|
||||
5. **Resolve version.** Default URL: `https://github.com/Sendspin/sendspin-go/releases/latest/download/sendspin-player-linux-arm64.tar.gz`. With `--version`: `https://github.com/Sendspin/sendspin-go/releases/download/<tag>/sendspin-player-linux-arm64.tar.gz`. Same logic produces the `dist/...` raw URL ref: `main` for default, `<tag>` for pinned.
|
||||
6. **Stop service if running.** `systemctl is-active --quiet sendspin-player && systemctl stop sendspin-player`.
|
||||
7. **Download + extract.** `curl -fSL <url> -o $TMP/sp.tar.gz`, `tar -xzf $TMP/sp.tar.gz -C $TMP`, `install -m 755 $TMP/sendspin-player /usr/local/bin/sendspin-player`. `$TMP` is `mktemp -d` and removed via `EXIT` trap.
|
||||
8. **Install systemd unit.** `curl -fSL <raw-dist-url>/systemd/sendspin-player.service -o /etc/systemd/system/sendspin-player.service`. Always overwritten.
|
||||
9. **Install env file (conditional).**
|
||||
- If `/etc/default/sendspin-player` does not exist, fetch `dist/systemd/sendspin-player.env` from raw GitHub.
|
||||
- If `--name` or `--device` were passed, write `SENDSPIN_PLAYER_OPTS="--name <n> --audio-device <d>"` to `/etc/default/sendspin-player` (overwriting). Each flag value is wrapped in single quotes with embedded single quotes escaped via the standard `'\''` pattern, so names like `Bob's Living Room` survive intact. Only the flags actually passed are emitted.
|
||||
- Otherwise (file exists, no flags), leave it alone.
|
||||
10. **Install YAML config (conditional).** If `/etc/sendspin/player.yaml` does not exist, `mkdir -p /etc/sendspin && curl -fSL <raw-dist-url>/config/player.example.yaml -o /etc/sendspin/player.yaml`. Otherwise leave it alone (preserves any `client_id` the daemon has already written back).
|
||||
11. **Reload + enable + start.** `systemctl daemon-reload && systemctl enable --now sendspin-player`.
|
||||
12. **Health check.** Sleep 2s; check `systemctl is-active sendspin-player`. If not active, print last 20 lines of `journalctl -u sendspin-player --no-pager` and exit non-zero.
|
||||
13. **Success message.** Print resolved version, config file path, env file path, and `journalctl -u sendspin-player -f` for live logs.
|
||||
|
||||
## Error handling
|
||||
|
||||
- `set -euo pipefail` at the top of the script.
|
||||
- Every download uses `curl -fSL` so a 404 (e.g. typo'd `--version`) exits cleanly with the curl error.
|
||||
- `EXIT` trap removes the staging tempdir and, on non-zero status, prints a one-line "If install failed mid-way, re-run the script — it's idempotent" hint.
|
||||
- The binary is `install -m 755`'d only after the tarball extracts cleanly. A failed download leaves `/usr/local/bin/sendspin-player` untouched.
|
||||
- Pre-flight failures print the *specific* missing requirement, never a generic "system not supported".
|
||||
|
||||
## Testing
|
||||
|
||||
- **Local smoke**: run in `arm64v8/debian:bookworm` (without systemd — verify deps install, binary lands, files in place; `systemctl` steps will fail loudly which is expected without an init system).
|
||||
- **Real Pi**: run the actual `curl | bash` on a fresh 64-bit Raspberry Pi OS install, confirm the player appears in mDNS and Music Assistant.
|
||||
- **Idempotency**: run twice on the Pi, confirm second invocation completes cleanly and the service stays up.
|
||||
- **Reconfigure**: run with `--name` after a vanilla install, confirm `/etc/default/sendspin-player` is rewritten and the service picks up the new name.
|
||||
- **Arch rejection**: run on `armv7l` (real Pi 2 or `qemu-user-static`), confirm clean error message naming the supported set.
|
||||
- **Uninstall**: `bash quickstart-pi.sh --uninstall`, confirm service stopped/disabled, binary and unit removed, config preserved.
|
||||
- **CI**: add `shellcheck scripts/quickstart-pi.sh` to the existing GitHub Actions lint workflow. No new workflow.
|
||||
|
||||
## Open questions
|
||||
|
||||
None at design time. Flag any post-implementation surprises in the PR.
|
||||
Reference in New Issue
Block a user