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](https://github.com/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](https://github.com/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.