distrobox-images/davinci/CLAUDE.md

DaVinci Resolve image — design notes

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).

Update 2026-09-09: the amd and nvidia targets both build successfully, tested with a real DaVinci_Resolve_21.1_Linux.run on Docker Desktop/WSL2 (Windows host, no distrobox available there). See "Build test" below for what was actually verified and how. What's still unverified: an actual distrobox create + davinci-run GUI launch on real Linux/GPU hardware — Windows can't test that part of the stack at all. Treat every "High" below as "confirmed by an actual build", "Medium/Low" as still resting on prior art alone.

Prior art checked before writing this

• zelikos/davincibox — Fedora toolbox base, actively maintained, tested by its maintainer against real AMD/Intel GPUs (no NVIDIA hardware). This is where the base image, davinci-dependencies package list, the silent-install invocation, and the patchelf fix all come from, read as raw files from GitHub (not paraphrased from search snippets).
• fat-tire/resolve — Rocky Linux base, raw podman/docker (no distrobox), bakes Resolve into the image at build time using the same -i -a -y installer flags. Cross-checking this against davincibox's setup-davinci (which uses the same flags, at container-runtime instead) is what gave confidence that -i -a -y is a real, working non-interactive install path and not a guess — two independent projects landed on the same flags.
• Universal Blue / openSUSE forum threads, Blackmagic forum thread: read for context, not copied from directly.

Why these choices

• Fedora toolbox base, not Ubuntu (unlike Houdini). Kept as-is from davincibox rather than switched to Ubuntu for consistency with Houdini, because it's the only base upstream has actually run real Resolve installs against, and it already ships the sudo/user bootstrap distrobox expects. The repo convention explicitly allows a different base per app.
• Resolve baked in at build time, not via a post-distrobox create setup script. davincibox installs Resolve after the box exists (setup-davinci), because it's meant to be a generic base image handed out to many users with different Resolve versions. This repo's own convention is the opposite: bake the actual software in and push a ready-to-run image (see Houdini). Confirmed this is actually possible (not just theoretically) by finding fat-tire/resolve, which does exactly this — bakes Resolve into a Dockerfile RUN step with no display attached, using the same installer flags.
• -i -a -y install flags. Not documented anywhere by Blackmagic directly (as far as this research found) — the confidence here comes from two independent community projects (davincibox, fat-tire/resolve) using the exact same flags to drive the same .run/AppImage installer non-interactively. QT_QPA_PLATFORM=minimal + SKIP_PACKAGE_CHECK=1 layered on top come from davincibox specifically (zelikos/davincibox#35) — fat-tire/resolve doesn't set these, so it's possible they're only needed in some environments; kept them since we're building with no display at all, which is the case they're meant for.
• patchelf fix, copied verbatim including the full library paths. davincibox's setup-davinci builds --add-needed arguments from full paths (/usr/lib64/libglib-2.0.so.0, ...), not bare sonames. This looks unusual — patchelf's --add-needed conventionally takes a soname — but it's copied exactly as upstream has it working, rather than "corrected" based on how patchelf is normally used elsewhere. If this turns out not to work, that's the first thing to check against upstream's current version of the script (it may have changed since this was written).
• amd variant installs both ROCm and Intel's intel-compute-runtime. Matches davincibox's single -opencl variant, which is the same reasoning Houdini's Dockerfile uses for "amd variant also works for Intel" — no separate Intel target. mesa-libOpenCL (rusticl) is removed first because it's confirmed (zelikos/davincibox#173) to break ROCm.
• nvidia variant is untouched (no OpenCL packages added). Matches Houdini's NVIDIA variant shape (nothing baked in, host driver only) but the actual runtime wiring differs — see the "NVIDIA gotcha" section in README.md. davincibox's README documents needing the NVIDIA Container Toolkit + CDI device injection (--device nvidia.com/gpu=all) rather than distrobox's simpler --nvidia flag, for reasons not fully explained in their docs (something about their toolbox target needing NVIDIA_VISIBLE_DEVICES/NVIDIA_DRIVER_CAPABILITIES env vars set at the container level, which --nvidia's driver-file bind-mount alone doesn't set up). Not resolved here; flagged as an open question for whoever tests this first.
• App menu entry uses Resolve's own shipped .desktop/icon files (/opt/resolve/share, /opt/resolve/graphics), unlike Houdini where one had to be hand-written from scratch. This is a real difference in what each app ships, not an inconsistency to "fix" — davincibox's add-davinci-launcher script does the same sed-based adaptation, simplified in the README here since we don't need its toolbox/distrobox branching (this repo is distrobox-only) or its remove mode.
• Not ported from davincibox: switcheroo-control multi-GPU handling (list-gpus/switcherooctl launch wrapping in run-davinci) and runtime GPU auto-detection in the launcher (lshw-based, only needed because davincibox ships one image covering all GPU vendors — this repo already splits that at build time via amd/nvidia targets). Both are real upstream features, deliberately left out here rather than overlooked — add them back from davincibox's run-davinci if dual-GPU laptop switching turns out to matter.

Build test (2026-09-09)

Ran on Docker Desktop (WSL2 backend, Windows host) with the real DaVinci_Resolve_21.1_Linux.run (free version) placed next to the Dockerfile — docker build --target amd then --target nvidia. No distrobox involved (Windows), so this only covers the image build itself, not an actual GUI launch.

• Dependency install (base stage, both variants): passed clean. All 165 packages in davinci-dependencies resolved and installed on fedora-toolbox:44 with 0 errors — confirms the list still matches current Fedora 44 repos.
• Silent install (-i -a -y, QT_QPA_PLATFORM=minimal, SKIP_PACKAGE_CHECK=1) actually works at Docker build time, no display attached. Installer output ended with DaVinci Resolve installed to /opt/resolve / Done. Only benign warnings: missing xdg-icon-resource/ xdg-mime/gtk-update-icon-cache (desktop-integration helpers not installed, not needed at build time) and a udev reload failure (no real udev/sysfs in a build container — expected). No AppImage magic-byte issue hit with this particular .run (that workaround, from fat-tire/resolve, is still not ported — add it back if a future version's .run fails --appimage-extract).
• patchelf fix ran successfully. find /opt/resolve/bin -executable -type f -exec patchelf ... reported patchelf: not an ELF executable for 3 files (non-ELF things under bin/ with the executable bit set, e.g. shell scripts) — harmless, and doesn't fail the build because find -exec cmd {} \; (semicolon form) does not propagate cmd's exit status to find's own. Verified with patchelf --print-needed that resolve and its sibling binaries now carry all 4 --add-needed entries.
• ldd /opt/resolve/bin/resolve (the actual entry point): zero missing libraries. This is the one that matters — confirms the dependency list is sufficient for the main binary as actually invoked.
• False alarm, worth remembering: running ldd directly on individual .so files under /opt/resolve/libs/*.so in isolation shows dozens of "not found" (libc++.so.1, every bundled Qt5/OpenCV/Kaldi/OpenEXR lib, etc.). This is not a real problem — resolve's own RPATH is $ORIGIN/../libs/:$ORIGIN/../libs/Fusion:... (old-style DT_RPATH, padded with a long run of x characters so Blackmagic's own installer can rewrite the real path post-install without changing the binary's size — same trick as the RESOLVE_INSTALL_LOCATION placeholder in the .desktop files). DT_RPATH on the main executable applies transitively to the whole process's library resolution, not just its own direct NEEDED entries — so at actual runtime, through resolve, all of these resolve fine. Testing a .so file in isolation loses that context and produces a misleading "missing" list. Lesson for next time: to check for real missing libraries in an RPATH-based bundle like this one, ldd only the actual entry point binary, not the library files underneath it — scanning every .so individually (the approach that worked for Houdini's Qt plugins, which don't use this RPATH trick) gives false positives here.
• The only genuinely missing library found: libcuda.so.1, needed by libDecoderCUDA.so (CUDA RAW decode path) — expected and correct, that comes from the host NVIDIA driver, not from anything baked into the image.
• nvidia target builds instantly (shares the cached base stage) and carries NVIDIA_VISIBLE_DEVICES=all/NVIDIA_DRIVER_CAPABILITIES=all as expected. Its actual GPU passthrough behavior (--nvidia vs CDI, see README) is still unverified — no NVIDIA hardware available to test from here either.
• Not exercised at all: actual GUI launch, license-free playback, OpenCL compute on real AMD/Intel hardware, audio, the app-menu-entry steps, Studio+dongle path. All of that needs a real Linux host with distrobox.

What's still unverified after this build test

Area	Confidence	Note
Base image + dependency list	High	Build-confirmed against Fedora 44 repos, 2026-09-09.
-i -a -y + QT_QPA_PLATFORM=minimal + SKIP_PACKAGE_CHECK=1 at Docker build time, no display	High	Build-confirmed: installer completed and reported success.
patchelf fix (paths, not sonames)	High	Build-confirmed: ran without failing the build, --print-needed shows the entries landed on resolve and siblings.
Dependency sufficiency for the actual entry point (ldd /opt/resolve/bin/resolve)	High	Build-confirmed: zero missing libraries.
AppImage magic-bytes workaround (fat-tire's Arch/Manjaro-specific issue)	Not ported	Not hit with the 21.1 .run tested here; add back from fat-tire/resolve's Dockerfile if a future version's --appimage-extract fails on it.
amd variant (ROCm + Intel packages install)	High	Build-confirmed: dnf install intel-compute-runtime rocm-opencl succeeded with no extra repos needed. Actual GPU compute correctness (OpenCL kernels running right) still unverified — needs real hardware.
nvidia variant / --nvidia vs CDI	Low	Still a real open question — see "NVIDIA gotcha" in README. Image builds fine either way; only the runtime GPU passthrough method is unverified.
App menu entry steps	Medium	Directly adapted from a working upstream script, simplified; confirmed the .desktop files exist at the documented paths (/opt/resolve/share/*.desktop), not run end-to-end.
Actual GUI launch / rendering / audio / licensing	Untested	Needs a real Linux host with distrobox + GPU — impossible to test from this Windows/Docker Desktop environment.

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 ../houdini/CLAUDE.md are for future-Claude context.