Install ALSA on first run

[Nicolas Palpacuer (NickPPC)]

Summary

On a host without ALSA the audio-module binary fails to start with libasound.so.2: cannot open shared object file and exits 127. Desktop images ship it and server or minimal container images do not, so the gap only appears on freshly provisioned machines — where it surfaces as model not registered on every resource depending on the speaker or microphone, reading like a config error rather than a missing .so. The tarball already bundles JACK and libdb; this adds a first_run.sh that installs ALSA the same way.

⚠️ first_run.sh exits non-zero when it cannot install the libraries, which aborts the machine's reconfiguration by design (local_robot.go). The machine keeps its previous working config and already-running modules keep running, rather than applying a config it cannot serve. No success marker is written on failure, so first_run retries automatically once the host is fixed.

Because the RDK only advances its stored config after the first_run phase succeeds, an aborted reconfiguration re-runs this script every cloud-config refresh (~10s). The install attempt is therefore rate-limited to once per 10 minutes so it does not hold the package-manager lock against an operator fixing the host by hand — the diagnostic and the non-zero exit still happen on every run. The stamp recording that rate limit sits beside the module directory (root-owned), not in /tmp, so it cannot be pre-created as a symlink by a local user and truncated by a root-run script.

Review guide

• first_run.sh is the entire change; everything else is packaging wiring. Start at main() at the bottom.
• The packaging needs all three hops to line up: exports_sources → CMake install → conan deploy(). Miss one and the script silently never reaches the machine.

Changes

• first_run.sh: checks for libasound.so.2 via ldconfig, installs the right package for the distro, re-verifies, and prints a copy-pasteable command if it is still missing
• meta.json: adds the first_run key, which the module did not previously declare
• CMakeLists.txt: install(PROGRAMS ...) rather than FILES, so the script keeps its executable bit — the RDK execs it directly
• conanfile.py: exports the script and copies it into module.tar.gz alongside run.sh
• README.md: documents the dependency and what to do if auto-install can't proceed

Testing

Verified in throwaway containers (all with empty package caches, i.e. the fresh-host case):

• ubuntu:24.04 — installs libasound2t64 and re-verifies the soname
• second run on the same host — no-op; macOS — no-op
• non-root with no passwordless sudo — exits 1, prints the manual command and the consequence
• two consecutive failing runs — the second still exits 1 but skips the package manager (throttle)

The script handles the Debian/Ubuntu 64-bit time_t rename by trying libasound2t64 then libasound2, so it works on noble and on jammy/bookworm without pinning a release. The soname is looked up through ldconfig, whose cache is architecture-aware, so no /usr/lib/<triplet> paths are hardcoded.

The packaging is confirmed against this PR's own CI artifact rather than by inspection — module-darwin-arm64 from the build job unpacks to:

drwx------  ./
-rwxr-xr-x  ./audio-module
-rwxr-xr-x  ./first_run.sh
-rw-r--r--  ./meta.json
-rwxr-xr-x  ./run.sh

i.e. first_run.sh lands at the tarball root next to meta.json with its executable bit intact, which is what the RDK needs to exec it.

Claude Code prompts used

• "Can you then chweck the error logs for Viam machine part <redacted> and tell me what needs to be installed on the machine to make it work?"
• "For the missing system libraries we identified previously, coould you make a PR against those modules to create or extend the frist_run file such that it installs those dependencies correctly (depending on the OS and architecture if applicable). Make sure to surface clear error messages for easier troubleshooting if something cannot be installed"