subwave-control

SUB/WAVE control

Bring the SUB/WAVE stack up or down. Nothing more. No builds, no pulls, no setup — if any of those are needed, hand off to the subwave-deploy skill.

This skill is checked into the SUB/WAVE repo. The repo root is the git repository that contains this skill — 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. All docker compose invocations run from docker/ inside $REPO. Shell state does not persist between commands, so re-derive $REPO (or substitute its value) in each command block below.

The three things you need to know

1. Two compose files = two modes.

   • Dev — docker-compose.dev.yml: Icecast + Liquidsoap + Controller only. Web runs separately as npm run dev on the host (port 7700).
   • Prod — docker-compose.yml: adds web (built image) and caddy (edge router). Only Caddy binds a host port. State defaults to <repo>/state (override with the STATE_DIR env).

2. Service ports (post-renumber): Web 7700, Controller 7701, Icecast 7702. The controller's /health endpoint returns {"status":"on-air"} once Liquidsoap is connected to Icecast — that's the canonical "is it up?" check.

3. Web dev is hot-reloaded but must be launched separately in dev mode. npm run dev in web/ is a long-running foreground process; in this skill, always run it as a background task. The Next.js port 7700 collides with macOS AirPlay Receiver in some setups — if you get EADDRINUSE on :7700, check lsof -nP -iTCP:7700 -sTCP:LISTEN and surface the conflict to the user rather than guessing.

Workflow

Step 0 — Detect what's running

cd "$REPO"
RUNNING_DEV=$(docker compose -f docker-compose.dev.yml ps -q 2>/dev/null)
RUNNING_PROD=$(docker compose -f docker-compose.yml ps -q 2>/dev/null)
WEB_DEV_PID=$(lsof -nP -iTCP:7700 -sTCP:LISTEN -t 2>/dev/null | head -1)