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.

SideFX Labs — baked in, not installed at runtime

Simon hit No such file or directory using Houdini's own in-app package installer for Labs. Root cause (confirmed, not guessed): this image never installed ca-certificates, so any HTTPS download from inside the container fails TLS verification — reproduced directly with wget against github.com inside a test build (wget exit 5, "cannot verify github.com's certificate"). The in-app installer's No such file or directory is almost certainly it shelling out to git (also never installed) for the same underlying reason: no working way to fetch anything over HTTPS. wget was already installed and used fine elsewhere in this Dockerfile, so the gap was specifically the missing CA bundle, not a missing downloader. Fixed by adding ca-certificates to the apt-get install list (base stage).

Rather than also install git and instruct Simon to run the in-app installer, Labs is fetched and baked in at build time:

Downloaded from a GitHub release tag (https://github.com/sideeffects/SideFXLabs/archive/refs/tags/<tag>.tar.gz), pinned via ARG SIDEFXLABS_VERSION, same pattern as HOUDINI_EULA_DATE — unpinned upstream, pick the newest tag whose target_commitish is Development and whose bundled SideFXLabs.json enable range covers this image's Houdini version. Checked via the GitHub releases API at writing time: tag 22.0.440 declares "enable": "houdini_version >= '22.0' and houdini_version < '22.5'", which covers this image's 22.0.429.
Extracted straight into $HFS/packages/SideFXLabs22.0/, with the vendored SideFXLabs.json copied up to $HFS/packages/SideFXLabs22.0.json unmodified. This location was not a guess: $HFS/packages is where Houdini's own shipped optional packages already live (confirmed by listing the real installed tree in a test build — apex, kinefx, ocio, sculpt, shotbuilder, texturepaint all follow the exact same <name>.json + <name>/ pattern there). It's also documented as a package search path independent of $HOME (https://www.sidefx.com/docs/houdini/ref/plugins.html), which matters specifically because distrobox bind-mounts the host's $HOME over whatever the image ships under $HOUDINI_USER_PREF_DIR — anything baked in there would be invisible at runtime. No edits to the vendored JSON were needed: its default "$HOUDINI_PACKAGE_PATH/SideFXLabs22.0" already resolves correctly, since HOUDINI_PACKAGE_PATH just means "the directory this json file itself lives in".
Verified end-to-end in a real build: ca-certificates fix lets wget fetch the release tarball; extracted tree has 452 .hda files under otls/; $HFS/packages/SideFXLabs22.0.json present and well-formed. Not verified against a real license + GUI launch (Apprentice activation needs a real SideFX login, out of scope for this check) — the Labs menu actually appearing in a running Houdini session is unconfirmed, though the mechanism matches Houdini's own shipped packages exactly.

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:

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.
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.
SideFX Labs baked into `$HFS/packages`	Medium	Build-time fetch + extraction confirmed (452 `.hda`s, well-formed json), and the target path matches Houdini's own shipped packages exactly — but never confirmed against a real license + GUI launch that the Labs menu actually appears.

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.

13 KiB Raw Permalink Blame History