distrobox-images/houdini/CLAUDE.md

Houdini image — design notes and debugging history

Context for whoever (Claude) touches this Dockerfile next. Simon doesn't need to read this — it's implementation reasoning, not usage docs (those are in README.md).

Why these choices

• Base image + install command copy SideFX's own docker/Ubuntu/Dockerfile (shipped inside the Houdini tarball under docker/Ubuntu/), not guessed. That reference folder has been deleted from this repo once its contents were folded in here — it only ever served as a source to copy from, and keeping it around invited drift between two copies of the same info.
• Ubuntu 22.04, not Rocky/RHEL. The tarball is gccXX.X-tagged (here gcc14.2), meaning the runtime needs a libstdc++ new enough for that build. Ubuntu's base image keeps libstdc++6 updated via regular package updates; RHEL-family distros pin their system toolchain for the whole OS lifetime, so a Rocky 9 base risks a GLIBCXX_x version mismatch depending on which Houdini build you're on. This was a real, not hypothetical, concern with the 22.0.429/gcc14.2 build tested here.
• --auto-install --accept-EULA <date>, no --make-dir, no --install-license. An earlier draft of this Dockerfile invented an --install-license <path> flag that doesn't exist, based on scripted- install docs that actually describe a different tool (houdini_installer, the newer credential-based launcher — irrelevant here, since it needs network + stored SideFX credentials at build time, which is worse for a private-registry-baked-tarball workflow). The flags actually used are copy-pasted from SideFX's own Dockerfile.
• EULA date is a plain YYYY-MM-DD, no SideFX- prefix. The SideFX-YYYY-MM-DD form belongs to houdini_installer's config file, not to houdini.install. Mixing the two up silently breaks --accept-EULA matching. Value as of writing: 2021-10-13 (from https://www.sidefx.com/legal/license-agreement/ — SideFX can update this without notice, it's not pinned/checked anywhere).
• /opt/hfs symlink is created explicitly. houdini.install's default behavior only creates a major.minor symlink (/opt/hfs22.0 here), not a generic /opt/hfs. The Dockerfile globs for the installed hfs[0-9]* dir and symlinks it to /opt/hfs itself, so houdini-run and the /etc/profile.d snippet don't need to know the exact version.

Runtime library list

SideFX's own package list in docker/Ubuntu/Dockerfile is built for headless hython/sesinetd use (their docker-compose.yml only ever runs hython or sesinetd as separate services, never the GUI). Running the actual houdinifx GUI needed 4 more libs, each found by ldd-checking the real binaries/plugins in a test build and confirmed missing before adding:

• libegl1 — EGL dispatch, houdinifx-bin linked against it directly.
• libatomic1 — houdinifx-bin/hython-bin both needed it.
• libxkbfile1 — same.
• libxcb-cursor0 — this one took the longest to find. Qt6's xcb platform plugin (libqxcb.so, under /opt/hfs<ver>/dsolib/Qt_plugins/platforms/) hard-depends on it (a known Qt6 change from Qt5, where cursor theming moved from Xcursor to xcb-cursor). Without it, Houdini fails at Qt platform-plugin init with a generic "no Qt platform plugin could be initialized" — nothing points at the actual missing symbol unless you ldd the plugin directly.

If a future Houdini/Qt version adds new failures here, the fastest diagnosis path is: ldd every .so under dsolib/Qt_plugins/ recursively (see git history of this file / session transcript for the exact one-liner), not guessing from the vague top-level Qt error message.

houdini-run strict-mode compatibility

houdini_setup_bash (sourced by houdini-run to set up $HFS/PATH/etc.) is not written for set -euo pipefail:

• It references variables that are legitimately unset in some code paths (set -u would abort).
• It does things like d=$(which java) expecting a silent empty result on failure (set -e would abort on the failed which).

Fix: wrap the source ./houdini_setup call with set +euo pipefail / set -euo pipefail around it, rather than trying to patch the vendor script.

NixOS / distrobox host environment leakage

Distrobox forwards the host shell's environment into the container by design (needed for DISPLAY, WAYLAND_DISPLAY, XDG_*, D-Bus, etc. to work at all for GUI apps). On a NixOS host that also sets its own LD_LIBRARY_PATH (observed here pointing at a Nix-store alsa-lib built against a much newer glibc than Ubuntu 22.04 ships), that leaks into the container and crashes Houdini's binaries at dynamic-link time (GLIBC_ABI_GNU2_TLS not found, etc.) — a library meant for the host's libc, loaded into a binary linked against the container's older libc.

houdini_setup_bash only ever prepends to LD_LIBRARY_PATH if it's already set — it never resets it. So houdini-run explicitly unset LD_LIBRARY_PATH before sourcing it, discarding whatever leaked in from the host and letting Houdini build its own from scratch. This is safe on any host, not just NixOS — it just happens to matter there.

This class of problem (host env leaking into the container and colliding with container-local binaries) is worth checking first if a new, unexplained crash shows up after this image has otherwise worked before.

sesinetd / Apprentice licensing — the two real bugs

Both now handled automatically inside houdini-run (not just documented as manual steps), found via /var/log/sidefx/sesinetd.log after a genuinely confusing symptom in the GUI:

1. License file permissions. sesinetd drops privileges to www-data after being started as root via sudo. The license file bind-mounted from the host (~/.houdini-apprentice/licenses:/usr/lib/sesi/licenses) is created with touch as the host user, so it's not writable by www-data inside the container. Result: activation's network round-trip to SideFX succeeds fine (curl-level success), but writing the resulting license locally fails — surfaced in the GUI as the deeply misleading "Success (curl error 0)" error dialog that just loops back to the install-license prompt with no indication anything is actually wrong. The real error only shows up in /var/log/sidefx/sesinetd.log: [FATAL - Licensing] [Manager] - Failed to open license file. Fix: houdini-run now chmod 666s the license file before starting sesinetd, every time, unconditionally.
2. Stuck self-signed TLS cert. If cert generation for sesinetd's HTTPS listener gets interrupted (observed here across our own repeated container kill/restart cycles during testing), it leaves 0-byte /usr/lib/sesi/ssl/auth.cert / auth.priv behind. On next start, sesinetd tries to read those, fails (Bad certificate chain: 'PEM lib'), and — rather than regenerating — spins retrying at ~100% CPU forever, never actually finishing startup or opening port 1715. No error surfaces in the GUI for this one at all; the only symptom is a pegged CPU core and a license dialog that never succeeds. Fix: houdini-run deletes those two files first if either is 0 bytes.

Also confirmed, contra a plausible-sounding but wrong worry: SideFX's own docker README warns that regular (non-floating) licenses need special "container enabled" entitlements to run sesinetd in Docker, working around it with network_mode: host in their own docker-compose.yml. That warning is about Docker's default isolated network namespace confusing the node-lock check. Distrobox shares the host's network namespace by default (no --unshare-netns), which is the same situation as SideFX's own workaround — so this doesn't apply here, and was confirmed by an actual successful Apprentice activation.

Confidence table (as of the last real end-to-end test)

Everything below was confirmed with an actual build + an actual distrobox create + houdini-run launch on a real AMD iGPU (Vega, raven) host, not just read from docs.

Area	Confidence	Note
Base image + install command	High	Matches SideFX's own Dockerfile; built end to end against the real 22.0.429/gcc14.2 tarball.
/opt/hfs symlink	High	Confirmed by test build.
EULA date value	Medium	2021-10-13 as of writing; unpinned, SideFX can change it.
Licensing works under distrobox's shared netns	High	Confirmed with a real Apprentice activation.
Runtime library list	High	Vendor's list + 4 libs added, all confirmed via ldd and an actual successful launch.
houdini-run strict-mode compatibility	High	Confirmed end to end.
sesinetd license-file-permission and stuck-cert fixes	High	Both bugs actually hit during testing, root-caused via /var/log/sidefx/sesinetd.log, fixed in houdini-run, confirmed working after the fix.
distrobox default hostname	Medium	Pinned explicitly (houdini-apprentice) rather than trusting the default, since Apprentice node-locks to hostname too.
GUI rendering via XWayland (Hyprland host)	High	Confirmed real AMD hardware acceleration (glxinfo: direct rendering, AMD Radeon Vega renderer, not llvmpipe). First launch was slow (container's first-run package install + cold start); later launches fluid.
AMD OpenCL (sims)	Low	Not set up; needs ROCm/rusticl. GL/Vulkan viewport is unaffected.
NVIDIA variant	Untested	Builds fine (same base, no extra packages), but never run against real NVIDIA hardware — only the amd target has been used end to end.

Repo-wide conventions

See the top-level ../README.md for the multi-software repo convention (one self-contained folder per app, shared registry setup notes) — that file is meant for Simon to read; this one and the top-level ../CLAUDE.md (if one exists) are for future-Claude context.