docker: Liquidsoap radio container (opam-built, version-selectable)

Dockerises the radio_conjurer.liq environment on Debian bookworm:

- Dockerfile.radio builds Liquidsoap through opam with build args for
  OPAM_VERSION (static binary), OCAML_VERSION (default 4.14.2; 2.1.x needs
  OCaml 4.x - prod ran 4.13.0, pass it for parity) and
  LIQUIDSOAP_VERSION (default 2.1.4, matching the script)
- LIQ_OPAM_PACKAGES installs exactly the features the script uses:
  mad+lame (mp3), cry (icecast), taglib (tags/replaygain), pulseaudio
  (mic/out), samplerate, inotify (watch-reload), ffmpeg
- ffmpeg.pref verdict: the Pi pin forced Debian's FFmpeg 5.x family
  (libavcodec59...) over RPi OS repo builds because the ocaml-ffmpeg
  bindings are compiled against those sonames; bookworm ships them
  natively so the container needs no pin (documented, not copied)
- pulse-access/audio group memberships baked in (were manual on the Pi);
  PULSE_MODE=internal runs a system-wide pulse with a null sink so the
  unmodified script works on a headless VM (mic = silence), host mode
  mounts the real socket, none for edited scripts
- mounts mirror the script's hardcoded paths (/home/pi/Conjurer,
  /home/pi/MediaFolder/mp3) so radio_conjurer.liq runs unmodified;
  entrypoint seeds script+params on first run (never overwrites), creates
  missing playlists, seeds placeholder icecast credentials (loud warning)
  and generates a silent emergency mp3 when the single() file is missing
- compose.radio.yaml: extra_hosts maps the script's host="radio" to
  ICECAST_HOST_IP; exposes 54321 (bot's RADIO_HARBOR /skip) and 9999
- docs: radio section with build args, pulse modes and the ffmpeg.pref /
  groups verdicts

Part 2 of this PR (splitting bot<->radio comms out of the musician into a
radio+betoniarka container) follows on this branch.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>

docker/Dockerfile.radio

@@ -0,0 +1,94 @@
+# Radio Conjurer - Liquidsoap runtime built through opam, so the OCaml,
+# opam and Liquidsoap versions are all selectable at build time.
+#
+# Build from the repository root, e.g.:
+#   docker build -f docker/Dockerfile.radio -t conjurer-radio .
+#   docker build -f docker/Dockerfile.radio -t conjurer-radio \
+#       --build-arg LIQUIDSOAP_VERSION=2.1.4 --build-arg OCAML_VERSION=4.14.2 .
+#
+# Version notes (matched to radio_conjurer.liq, which targets 2.1.4):
+# * Liquidsoap 2.1.x requires OCaml 4.x - it does NOT build on OCaml 5.
+#   Production ran the 4.13.0 switch; 4.14.x is the maintained 4.x line and
+#   builds 2.1.4 fine. Pass OCAML_VERSION=4.13.0 for bit-for-bit parity.
+# * The ocaml-ffmpeg bindings compatible with 2.1.4 target the FFmpeg 5.x
+#   library family (libavcodec59/libavformat59/libavutil57...). Debian
+#   bookworm ships exactly that, which is why this image needs NO ffmpeg
+#   pinning: the old ffmpeg.pref (Pin-Priority 1001 on deb.debian.org) only
+#   existed to force those Debian builds over the Raspberry Pi OS repo's
+#   conflicting ones. Single-repo container = the pin is redundant.
+FROM debian:bookworm-slim
+
+ARG OPAM_VERSION=2.1.5
+ARG OCAML_VERSION=4.14.2
+ARG LIQUIDSOAP_VERSION=2.1.4
+# Optional liquidsoap features, resolved together with liquidsoap by opam.
+# These cover everything radio_conjurer.liq uses:
+#   mad+lame  - mp3 decode/encode (%mp3 icecast stream)
+#   cry       - output.icecast
+#   taglib    - tag/replaygain metadata
+#   pulseaudio- input.pulseaudio (mic) + output.pulseaudio
+#   samplerate- resampling
+#   inotify   - playlist(reload_mode="watch")
+#   ffmpeg    - decode fallback + replaygain computation
+ARG LIQ_OPAM_PACKAGES="mad lame cry taglib pulseaudio samplerate inotify ffmpeg"
+
+# System libraries: build deps for the opam packages above plus the matching
+# runtime libs. The libav*-dev list mirrors the old ffmpeg.pref family.
+RUN apt-get update && apt-get install -y --no-install-recommends \
+        build-essential m4 pkg-config git curl ca-certificates unzip rsync \
+        libpcre3-dev libgmp-dev zlib1g-dev \
+        libmad0-dev libmp3lame-dev libtag1-dev \
+        libpulse-dev libsamplerate0-dev \
+        libavcodec-dev libavformat-dev libavutil-dev libavfilter-dev \
+        libavdevice-dev libswresample-dev libswscale-dev libpostproc-dev \
+        ffmpeg \
+        pulseaudio pulseaudio-utils \
+    && rm -rf /var/lib/apt/lists/*
+
+# Group membership for PulseAudio/ALSA access. On the Pi this was done by
+# hand for the system-wide pulse socket; in the image it is baked in. The
+# 'pulse-access' group comes with the pulseaudio package.
+RUN usermod -aG audio,pulse-access root
+
+# opam as a static binary so OPAM_VERSION is a real choice (apt would pin us
+# to whatever bookworm ships).
+RUN ARCH=$(uname -m) \
+    && curl -fsSL -o /usr/local/bin/opam \
+       "https://github.com/ocaml/opam/releases/download/${OPAM_VERSION}/opam-${OPAM_VERSION}-${ARCH}-linux" \
+    && chmod +x /usr/local/bin/opam
+
+# OCaml switch + liquidsoap and its optional feature libraries in one solve,
+# so liquidsoap is compiled WITH those features enabled.
+RUN opam init -y --bare --disable-sandboxing \
+    && opam switch create default "${OCAML_VERSION}" \
+    && opam install -y "liquidsoap.${LIQUIDSOAP_VERSION}" ${LIQ_OPAM_PACKAGES} \
+    && opam clean -a -c -s --logs
+
+ENV PATH="/root/.opam/default/bin:${PATH}"
+
+# Build-time smoke test: the binary runs and reports the requested version.
+RUN liquidsoap --version
+
+# Minimal system-wide pulse config for headless VMs (PULSE_MODE=internal):
+# a null sink so output.pulseaudio()/input.pulseaudio() work with no sound
+# hardware (mic becomes silence, which blank.strip already gates out).
+COPY docker/pulse-system.pa /etc/pulse/system.pa
+
+# The script and its persistent params are seeded into the data volume on
+# first run (never overwritten), so live edits survive image rebuilds.
+WORKDIR /app
+COPY conjurer_musician/radio_conjurer.liq ./radio_conjurer.liq
+COPY conjurer_musician/script.params ./script.params
+COPY docker/entrypoint.radio.sh /usr/local/bin/entrypoint.sh
+RUN chmod +x /usr/local/bin/entrypoint.sh
+
+# Mount points mirror the paths hardcoded in radio_conjurer.liq, so the
+# script runs unmodified: data at /home/pi/Conjurer, music at
+# /home/pi/MediaFolder/mp3.
+VOLUME ["/home/pi/Conjurer", "/home/pi/MediaFolder/mp3"]
+
+# 54321 = harbor /skip (the bot's RADIO_HARBOR), 9999 = interactive harbor.
+EXPOSE 54321 9999
+
+ENTRYPOINT ["/usr/local/bin/entrypoint.sh"]
+CMD ["liquidsoap", "/home/pi/Conjurer/radio_conjurer.liq"]

docker/compose.radio.yaml

@@ -0,0 +1,39 @@
+# Radio (Liquidsoap) VM. Run from the repository root:
+#   docker compose -f docker/compose.radio.yaml up -d --build
+#
+# Version pins are build args - override via environment, e.g.:
+#   LIQUIDSOAP_VERSION=2.1.4 OCAML_VERSION=4.13.0 \
+#     docker compose -f docker/compose.radio.yaml up -d --build
+services:
+  conjurer-radio:
+    build:
+      context: ..
+      dockerfile: docker/Dockerfile.radio
+      args:
+        OPAM_VERSION: ${OPAM_VERSION:-2.1.5}
+        OCAML_VERSION: ${OCAML_VERSION:-4.14.2}
+        LIQUIDSOAP_VERSION: ${LIQUIDSOAP_VERSION:-2.1.4}
+    image: conjurer-radio:latest
+    container_name: conjurer-radio
+    restart: unless-stopped
+    environment:
+      # internal = null-sink pulse inside the container (headless VM default)
+      # host     = mount the host pulse socket below and set PULSE_SERVER
+      PULSE_MODE: ${PULSE_MODE:-internal}
+      # PULSE_SERVER: unix:/tmp/pulseaudio.socket
+    extra_hosts:
+      # radio_conjurer.liq streams to host="radio" - point it at icecast.
+      - "radio:${ICECAST_HOST_IP:-192.168.1.12}"
+    ports:
+      - "54321:54321"   # harbor /skip - the bot's CONJURER_RADIO_HARBOR
+      - "9999:9999"     # interactive harbor (keep LAN-only!)
+    volumes:
+      # Playlists, logs, script.params, icecast_credentials.json, the script
+      # itself (seeded on first run) - paths mirror the ones hardcoded in
+      # radio_conjurer.liq so it runs unmodified.
+      - /srv/radio/data:/home/pi/Conjurer
+      # The mp3 library. Writable because the entrypoint seeds a silent
+      # emergency-fallback mp3 when the hardcoded single() file is missing.
+      - /srv/radio/music:/home/pi/MediaFolder/mp3
+      # PULSE_MODE=host: uncomment and adjust
+      # - /tmp/pulseaudio.socket:/tmp/pulseaudio.socket

docker/entrypoint.radio.sh

@@ -0,0 +1,66 @@
+#!/bin/sh
+# Prepare the radio volumes so radio_conjurer.liq boots on a fresh VM, then
+# start (or point at) PulseAudio and exec liquidsoap. Existing files are never
+# overwritten - live-edited script/params/playlists always win.
+set -e
+
+DATA="${RADIO_DATA_DIR:-/home/pi/Conjurer}"
+MUSIC="${RADIO_MUSIC_DIR:-/home/pi/MediaFolder/mp3}"
+mkdir -p "$DATA" "$MUSIC"
+
+# Seed the script + persistent interactive params from the image on first run.
+[ -e "$DATA/radio_conjurer.liq" ] || cp /app/radio_conjurer.liq "$DATA/"
+if [ ! -e "$DATA/script.params" ]; then
+    if [ -e /app/script.params ]; then cp /app/script.params "$DATA/"; else : > "$DATA/script.params"; fi
+fi
+
+# Playlists + logs the script watches/writes; empty files keep it happy until
+# the musician/betoniarka populate them.
+for f in all_playlist.playlist priority_queue.playlist hit.playlist \
+         request.playlist jingles.playlist persistence.log; do
+    [ -e "$DATA/$f" ] || : > "$DATA/$f"
+done
+
+# Icecast credentials are a secret - never baked into the image. Seed a
+# placeholder so the script can parse the JSON, but shout about it.
+if [ ! -e "$DATA/icecast_credentials.json" ]; then
+    printf '{\n"password" : "CHANGE_ME"\n}\n' > "$DATA/icecast_credentials.json"
+    echo "WARNING: seeded placeholder icecast_credentials.json - the icecast" >&2
+    echo "         output will be rejected until you set the real password!" >&2
+fi
+
+# single() aborts the whole script when its file is missing; guarantee the
+# emergency fallback exists (5s of silence beats a dead radio).
+EMERGENCY="$MUSIC/Youtube/Dr. Peacock - Trip to Ireland [GvrvQTUbUcA].mp3"
+if [ ! -e "$EMERGENCY" ]; then
+    mkdir -p "$MUSIC/Youtube"
+    if ffmpeg -loglevel error -f lavfi -i anullsrc=r=44100:cl=stereo -t 5 \
+              -codec:a libmp3lame -q:a 9 "$EMERGENCY"; then
+        echo "WARNING: emergency track was missing - generated silent placeholder" >&2
+    else
+        echo "WARNING: could not create emergency track; single() may abort" >&2
+    fi
+fi
+
+# PulseAudio wiring:
+#   internal (default) - system-wide pulse inside the container with a null
+#                        sink (see /etc/pulse/system.pa); no sound hardware
+#                        needed, mic path reads silence.
+#   host               - use a socket mounted from the host; set PULSE_SERVER
+#                        (e.g. unix:/tmp/pulseaudio.socket) in the env file.
+#   none               - you edited the script to drop pulse in/out.
+case "${PULSE_MODE:-internal}" in
+    internal)
+        pulseaudio --system --daemonize=yes --disallow-exit --exit-idle-time=-1 \
+            || echo "WARNING: internal pulseaudio failed to start" >&2
+        export PULSE_SERVER="${PULSE_SERVER:-unix:/var/run/pulse/native}"
+        ;;
+    host)
+        [ -n "$PULSE_SERVER" ] || echo "WARNING: PULSE_MODE=host but PULSE_SERVER is unset" >&2
+        ;;
+    none)
+        ;;
+esac
+
+cd "$DATA"
+exec "$@"

docker/pulse-system.pa

@@ -0,0 +1,10 @@
+#!/usr/bin/pulseaudio -nF
+# Minimal system-wide PulseAudio config for the radio container running on a
+# headless VM (PULSE_MODE=internal). Mirrors the Pi's setup (unix socket,
+# anonymous auth) but replaces the Lexicon Lambda USB device with a null
+# sink: output.pulseaudio() plays into the void and input.pulseaudio() (the
+# mic path) reads silence from the sink monitor.
+load-module module-null-sink sink_name=radio_null sink_properties=device.description=RadioNullOutput
+load-module module-native-protocol-unix auth-anonymous=1
+set-default-sink radio_null
+set-default-source radio_null.monitor

docs/deployment/DOCKER_PROXMOX.md

@@ -223,6 +223,62 @@ those two files into the same `/srv/musician/data` directory (or set
 `/stream` page template is served from the baked-in `/app/stream.html`
 (override with `CONJURER_STREAM_TEMPLATE` if you customise it).
 
+### 3e. Radio (Liquidsoap) container
+
+`docker/Dockerfile.radio` builds the full Liquidsoap environment through
+**opam**, with the OCaml/opam/Liquidsoap versions selectable at build time:
+
+| Build arg | Default | Notes |
+|-----------|---------|-------|
+| `LIQUIDSOAP_VERSION` | `2.1.4` | what `radio_conjurer.liq` targets |
+| `OCAML_VERSION` | `4.14.2` | 2.1.x needs OCaml **4.x** (never 5); prod ran 4.13.0 — pass it for exact parity |
+| `OPAM_VERSION` | `2.1.5` | static binary from GitHub releases |
+| `LIQ_OPAM_PACKAGES` | `mad lame cry taglib pulseaudio samplerate inotify ffmpeg` | exactly the features the script uses (mp3 in/out, icecast, tags/replaygain, pulse mic/out, watch-reload) |
+
+```bash
+sudo mkdir -p /srv/radio/data /srv/radio/music
+# put the real password in place (otherwise a CHANGE_ME placeholder is seeded):
+echo '{ "password" : "..." }' | sudo tee /srv/radio/data/icecast_credentials.json
+
+ICECAST_HOST_IP=192.168.1.12 docker compose -f docker/compose.radio.yaml up -d --build
+docker logs -f conjurer-radio
+```
+
+The container mounts data at **`/home/pi/Conjurer`** and music at
+**`/home/pi/MediaFolder/mp3`** — the exact paths hardcoded in the script — so
+`radio_conjurer.liq` runs **unmodified**. The script + `script.params` are
+seeded into the volume on first run and never overwritten (live edits
+survive rebuilds). Missing playlists are created empty and a silent
+emergency-fallback mp3 is generated if the `single()` file is absent, so the
+script always boots. `host="radio"` (the icecast output) resolves via the
+compose `extra_hosts` entry — set `ICECAST_HOST_IP`.
+
+Point the bot at this VM: `CONJURER_RADIO_HARBOR=http://RADIO_VM_IP:54321`
+(the harbor `/skip` endpoint lives in the script itself).
+
+**PulseAudio** (`PULSE_MODE` env):
+- `internal` (default) — a system-wide pulse daemon runs inside the container
+  with a **null sink** (`docker/pulse-system.pa`): no sound hardware needed,
+  `output.pulseaudio()` plays into the void and the `input.pulseaudio()` mic
+  path reads silence (which `blank.strip` already gates out). Right choice
+  for a headless Proxmox VM.
+- `host` — mount the host's pulse socket and set `PULSE_SERVER`, for a VM
+  with real audio hardware (the Pi's Lexicon Lambda setup).
+- `none` — you removed the pulse in/out from the script.
+
+**Verdicts on the old Pi setup quirks** (asked during containerisation):
+- `ffmpeg.pref` (Pin-Priority 1001 on the `libavcodec59/libavformat59/…`
+  family): it **did have a purpose** — the opam-built ocaml-ffmpeg bindings
+  for 2.1.x are compiled against Debian bookworm's FFmpeg 5.x sonames, and
+  the pin forced those over conflicting Raspberry Pi OS repo builds (even as
+  a downgrade). In this single-repo container the same versions come
+  naturally, so **no pin is needed** — documented here so it doesn't get
+  cargo-culted forward.
+- adding root to `pulse-access`/`audio` groups: needed on the Pi for the
+  system-wide pulse socket and ALSA device access. The image bakes the same
+  memberships in (`usermod -aG audio,pulse-access root`) — harmless with the
+  internal null sink, required for `PULSE_MODE=host`.
+
 ---
 
 ## 4. Networking & auth