--- name: icey-server-operator description: Safely build, validate, package, release, and operate the icey-server CLI and media server surface. --- # icey-server Operator Workflow This is a portable skill document for agents working in `nilstate/icey-cli`. Use it to preserve the repo's build, validation, packaging, and operator bring-up conventions. The file is useful as plain project documentation. Tools that understand `SKILL.md`, including runx, can optionally pair it with execution, verification, and receipts. ## Evidence Sources This workflow is grounded in these repo files: - `README.md`: native quick start, Docker demo path, repo workflow, runtime modes, endpoints, browser smoke notes, and bring-up order. - `CMakeLists.txt`: C++20 project shape, `ICEY_SOURCE_DIR`, icey component requirements, install layout, and web UI install destination. - `CMakePresets.json`: `dev` and `release` configure/build presets using a sibling `../icey` checkout. - `Makefile`: canonical wrapper targets for configure, build, web, install, package, release, Docker, package-manager validation, and the macOS-only `facetime-demo` helper. - `web/package.json`: Vite build and Playwright smoke commands for Chromium, Firefox, WebKit, and Docker smoke. - `.github/workflows/ci.yml`: Linux CI contract using Ubuntu 24.04, GCC 13, pinned `ICEY_VERSION`, web build, staged install, browser smoke, and package-manager cutover. - `.github/workflows/release.yml`: release package, Docker image, GitHub release assets, and optional package-manager publication flow. - `.github/workflows/publish-package-managers.yml`: Homebrew, AUR, APT, and rendered manifest publication gates. - `packaging/README.md`: package-manager model, artifact names, generator scripts, and validation expectations. - `docker/README.md`: fastest demo path, host-networking assumptions, runtime overrides, and Compose source path. - `docs/facetime-on-macbook.md`: macOS realtime path. Single-process bring-up via the `avfoundation:` URL scheme dispatched by `MediaCapture::openFile`. Covers permission prompts, audio resampler bring-up, and the speaker default-mute. - `scripts/facetime-demo.sh`: one-command single-process bring-up of `icey-server --source 'avfoundation:0:none'` on macOS, fronted by the `make facetime-demo` target. - `VERSION` and `ICEY_VERSION`: release context for this repo and the pinned core `nilstate/icey` dependency. At generation time this repo declared icey-server 0.2.3 and pinned icey 2.4.9. ## When To Use This Skill Use this skill when an agent needs to: - change `icey-server` C++ server behavior, CLI flags, config handling, operator endpoints, or install layout - update the bundled web UI or browser smoke expectations - validate native builds against a sibling `nilstate/icey` checkout - modify Docker demo behavior or runtime environment variables - modify packaging, release metadata, package-manager manifests, or publication workflows - help an operator bring up `stream`, `record`, `relay`, TURN, RTSP, or TLS paths without mixing failure domains Do not use this skill to change core media primitives in `nilstate/icey`; that belongs in the core repo. This repo consumes the pinned core release through `ICEY_VERSION`. ## Inputs To Inspect First Always inspect these before planning changes: - `README.md` for the public operator contract and CLI option list - `Makefile` for preferred local commands - `CMakePresets.json` and `CMakeLists.txt` for build shape and dependency wiring - `ICEY_VERSION` before assuming core API behavior - `.github/workflows/ci.yml` before changing validation expectations - `web/package.json` before changing browser smoke behavior - `packaging/README.md` and `scripts/*release*` before changing release or package-manager output - `docker/README.md` and `docker/*` before changing demo behavior If a requested change touches release output, inspect `VERSION`, `CHANGELOG.md`, `scripts/validate-release-metadata.sh`, and `scripts/package-manager-check.sh` in the same pass. ## Safe Operating Rules - Keep the express demo path simple: `docker run --rm --network host 0state/icey-server:latest`, then `http://localhost:4500`. - Do not claim Safari support from Linux Playwright WebKit results; the README explicitly withholds that claim until Apple-platform validation exists. - Keep runtime bring-up staged: local `stream` without TURN, then `record`, then `relay`, then TURN-enabled external or NAT testing. - Treat `--doctor` as the first machine-readable preflight for operator-facing runtime changes. - Preserve the pinned `ICEY_VERSION` model. Do not silently float to `nilstate/icey` main in release or CI paths. - Keep package-manager output tied to real artifacts. Do not emit placeholder manifests for package managers without a matching archive and checksum. - Do not weaken CI coverage when changing C++, web UI, packaging, or release surfaces. - Do not add hosted service assumptions; the README positions the app as one binary plus local ports. ## Workflow ### 1. Classify The Change Map the request to one or more surfaces: - `server`: C++ server, CLI flags, config, endpoints, runtime modes - `web`: Vite UI, Symple client/player integration, browser smoke - `docker`: published image, Compose source path, host-networking demo - `packaging`: staged layout, tar/zip/deb/APT/package-manager manifests - `release`: VERSION, ICEY_VERSION, changelog, GitHub release assets, Docker Hub - `docs`: README, docker README, packaging README, operator instructions If the change crosses surfaces, plan validation for each touched surface before editing. ### 2. Build Or Configure Locally Preferred source-backed path with the sibling `icey` checkout: ```bash cmake --preset dev cmake --build --preset dev ``` Equivalent Makefile path: ```bash make configure make build ``` If the sibling checkout is not at `../icey`, pass `ICEY_SOURCE_DIR=/path/to/icey` explicitly. ### 3. Validate Runtime Readiness Use `--doctor` before claiming the server is runnable: ```bash ./build-dev/src/server/icey-server --doctor ``` For RTSP paths, start from the tracked example: ```bash cp config.rtsp.example.json config.local.json $EDITOR config.local.json ./build-dev/src/server/icey-server --config config.local.json --doctor ./build-dev/src/server/icey-server --config config.local.json ``` For a browser-visible local app, build the web UI first: ```bash make web-install make web-build ./build-dev/src/server/icey-server --web-root web/dist --source /path/to/video.mp4 ``` ### 4. Validate Browser And Demo Paths For UI changes or media-path claims, run the Chromium smoke path that CI treats as authoritative: ```bash npm --prefix web ci npm --prefix web run build npm --prefix web run test:smoke:chromium ``` For the published-image demo contract, keep the public command stable: ```bash docker run --rm --network host 0state/icey-server:latest ``` For local source-backed Docker validation: ```bash docker compose -f docker/compose.yaml up --build ``` For the macOS realtime FaceTime path, exercise the dedicated helper. It runs a single icey-server process that opens AVFoundation directly via the `avfoundation:` URL scheme; `Ctrl-C` tears it down: ```bash make facetime-demo ``` That target wraps `scripts/facetime-demo.sh`. macOS-only because of the avfoundation input. Setup details, including the device permission prompt, the audio capture default, and the speaker default-mute, are documented in `docs/facetime-on-macbook.md`. ### 5. Validate Packaging Or Release Changes For staged app layout changes: ```bash make install ``` For release metadata only: ```bash make release-metadata-check ``` For the full package-manager cutover contract: ```bash make package-managers ``` This must validate Linux tar/zip archives, Debian package contents, APT repo archive, Homebrew formula, AUR PKGBUILD, Nix expression, SHA256SUMS, and Windows-facing manifests only when real Windows artifacts exist. ### 6. Report Results A useful agent result should report: - changed surfaces - commands run - whether `ICEY_VERSION` was relevant - browser engine used for smoke validation - package artifacts validated, if any - runtime mode tested: `stream`, `record`, `relay`, TURN, RTSP, or TLS - any skipped validation and the concrete reason Do not collapse failures into generic language. If a check fails, preserve the exact command, exit behavior, and likely surface. ## Expected Outputs For implementation work, produce a concise change summary plus validation evidence. For operator help, produce an ordered bring-up path with the first command the operator should run next. For packaging or release work, name every artifact family affected. ## Optional Compatible Tooling Note This file is a portable `SKILL.md`. Agents and tools that understand `SKILL.md` can use it as repo workflow context. runx can optionally pair it with a registry binding for execution, verification, and receipts, but this repo does not require runx to use the file.