SUB/WAVE deploy

SUB/WAVE deploy

Bring the SUB/WAVE radio stack up — from a fresh checkout or from an already-running install — with the minimum churn the situation needs. A first-time setup takes a few minutes (build + first jingle render). A clean update with no rebuild takes seconds; a full rebuild a minute or two.

The user has authorised free action on this hot path — scripts/setup.sh, git pull, docker compose build, up -d, generate-jingles.sh, log scans, health probes. Pause and confirm only for the genuinely destructive moves listed at the bottom.

The five facts the workflow turns on

1. Two compose files, two shapes.

   • docker-compose.dev.yml — dev variant (Mac smoke-test): Broadcast (icecast2 + liquidsoap) + Controller only. Web runs separately via npm run dev. State at ./state.
   • docker-compose.yml — production single-host: adds web and caddy. Only Caddy binds a host port. State at ${STATE_DIR:-<repo>/state} — repo-local by default, same as dev.
   • Detect which is up from docker compose -f <file> ps. Caddy maps to host port ${CADDY_PORT:-7700} (0.0.0.0:7700->80/tcp by default). Always read the actual port from ps, never hardcode — operators can override via CADDY_PORT in docker/.env.

2. Controller and Broadcast COPY their assets at build time, they do not bind-mount them in prod. docker compose restart <svc> reruns the same baked-in code/config and does nothing for source changes. Source changes need up -d --build <svc>. This is the single most common deploy mistake. (Liquidsoap lives inside the broadcast image, so radio.liq edits in prod also need --build broadcast, not a plain restart.)

3. Web in dev is hot-reloaded (Next.js npm run dev); web in prod is a built standalone image and needs --build on any web/** change.

4. The IPC between Controller and Broadcast (liquidsoap side) is file-based through the shared state/ (mounted at /var/sub-wave). When you recreate one of them, in-flight next.txt/say.txt/now-playing.json may be mid-write — accept a few-second blip; don't keep recreating to "fix" it. But there is a worse failure here, and it has bitten in production: a near-simultaneous recreate of both controller and broadcast (which is exactly what up -d --build controller web triggers, because the depends_on graph also recreates broadcast) can have Liquidsoap pick up a bad/empty IPC request and wedge a source into a fail/blank loop. The result is silent but invisible: /api/health still says on-air, /stream.mp3 still flows bytes, /api/now-playing still rotates tracks — but the audio is digital silence (~-91 dB). The cure is a plain docker compose ... restart (no rebuild — code is already baked in); it clears the wedged source state. The detector is an audio-level probe, not the health endpoint — see Step 5.

5. Compose rebuilds dependencies, but should no longer recreate them. up -d --build controller also BUILDS broadcast (the controller depends_on it). Before the compose files set provenance: false / sbom: false, BuildKit's per-build attestation gave that unchanged, cached image a new id on the containerd image store, so compose recreated the mixer and dropped every listener on a controller-only deploy. With the attestation off the rebuild is byte-identical and broadcast stays up. If broadcast IS recreated with no liquidsoap/, sounds/ or docker/ change, compare docker inspect sub-wave-broadcast -f '{{.Image}}' before and after — a new id with an old Created time means the build stopped being reproducible again.

Workflow

This skill is checked into the SUB/WAVE repo. $REPO below is the repo root — derive it once, don't hardcode it:

REPO=$(git -C "<this skill's base directory>" rev-parse --show-toplevel)

<this skill's base directory> is the absolute path shown as "Base directory for this skill" when the skill loads. Shell state does not persist between commands, so re-derive $REPO (or substitute its value) in each block below.

Step 0 — Detect the install state

Before anything else, figure out which mode you're in. Three possibilities:

cd "$REPO"