OCI Assembly — Required Post-Install Steps#
elements/oci/bluefin.bst assembles the final bootc image from staged layers.
After all packages are installed it runs several post-install steps before
calling build-oci. These steps are load-bearing — removing or reordering
them breaks the deployed image in ways that only appear after a bootc switch.
| Step | Command | Why |
|---|---|---|
| System users | systemd-sysusers --root /layer | Creates system accounts (e.g. gdm) needed at runtime. Without this, GDM cannot start a greeter session. |
| GLib schemas | glib-compile-schemas /layer/usr/share/glib-2.0/schemas | Compiles dconf schema cache; missing cache breaks settings reads. |
| dconf DB | dconf update /layer/etc/dconf/db | Writes compiled dconf database; required for GNOME defaults. |
| Linker cache | ldconfig -r /layer | Rebuilds /etc/ld.so.cache for the sysroot. Without this, any library SO version bump leaves the deployed system with a stale linker cache after bootc switch, causing dlopen() failures on first boot. |
The ldconfig rule#
Every time a library with a versioned SO name is bumped (Mesa libgallium-X.Y.Z.so,
Pipewire libpipewire-X.Y.so, etc.), the linker cache in the running system's
/etc/ld.so.cache still points at the old SO name after bootc switch. The new
image's /usr has the new SO, but /etc/ld.so.cache is not automatically
regenerated by bootc's 3-way merge.
ldconfig -r /layer in the image build writes a correct cache into the image's
/etc/ld.so.cache. On deployment, bootc's merge adopts the image's version of
this file, so the deployed system starts with a correct cache.
Real regression (PR #497): The junction bump upgraded Mesa 26.0.5 → 26.0.6.
libgallium-26.0.5.so was replaced by libgallium-26.0.6.so. dri_gbm.so has
no RPATH and relies entirely on the linker cache. After bootc switch, the stale
cache caused GNOME Shell to report Failed to open gpu '/dev/dri/card1': No such file or directory / No GPUs found on every boot — GDM looped and never showed
a login screen. Fix: sudo ldconfig on the affected system, and this ldconfig -r /layer step in the build to prevent recurrence.
If you are adding a new post-install step to
elements/oci/bluefin.bst, insert
it beforeldconfig -r /layerso the linker cache reflects the final
installed state.
