apt/dpkg DB as a sysext feature

[bsherman]

It would be nice to have the apt/dpkg DB available for users to query which packge ones what file, etc. However, the system is immutable and the pkg DB uses disk space for limited value.

Thus, pkg DB is not included in the base image.

Ideally, we create a sysext, installable as a feature, which provides the apt/dpkg DB for all other features provided by cayo/snow. Worst case, the pkg DB would have more packages than are actually installed, assuming not all features are installed.

[bketelsen]

— Automated by Yeti —

Implementation Plan

Now I have a thorough understanding of the repo. Here's the implementation plan:

---

Implementation Plan: apt/dpkg DB as a systemd-sysext

Context

Cayo is an immutable Debian bootc-based server image. The Containerfile's build process uses --mount=type=cache for /var/lib/apt and /var/lib/dpkg/updates, meaning those directories are not persisted into the final image — they exist only during build. The issue requests making the dpkg/apt database available as an optional systemd-sysext so users can query package info (e.g., dpkg -S /usr/bin/foo) without bloating the base image.

Approach

Create a second container build that produces a sysext image (a raw disk image or directory tree conforming to systemd-sysext conventions). This sysext overlays the dpkg/apt database directories onto the immutable root when activated via systemd-sysext merge.

A sysext must contain:

• usr/lib/extension-release.d/extension-release.<name> — metadata tying it to the OS
• The payload files under usr/ (sysexts can only overlay /usr/ and /opt/)

Since dpkg/apt databases live under /var/lib/dpkg/ and /var/lib/apt/, they cannot be directly provided by a sysext (which is limited to /usr/ and /opt/). There are two options:

1. Relocate the DB into /usr/share/cayo/pkg-db/ inside the sysext and provide wrapper scripts/symlinks — this is the pragmatic approach.
2. Use a confext (systemd-confext) which can overlay /etc/ — but that still doesn't cover /var/.

The most practical solution: build the sysext with the DB under /usr/share/dpkg-db/ and /usr/share/apt-db/, and include small wrapper scripts in /usr/local/bin/ that point dpkg/apt queries at the relocated DB. Alternatively, just ship the database at /usr/share/cayo/pkg-db/ and document that users can query it with dpkg --admindir=/usr/share/cayo/pkg-db/dpkg ....

Files to Create/Change

1. sysext/Containerfile.pkg-db (new)

A dedicated Containerfile that:

• Uses the same base image (ghcr.io/frostyard/debian-bootc-core:latest)
• Runs the same apt-get install commands (or sources the existing build_files/build script) to populate the dpkg/apt databases
• Copies the resulting /var/lib/dpkg/ and /var/lib/apt/lists/ into the sysext layout:
  • /usr/share/cayo/pkg-db/dpkg/ — the dpkg database
  • /usr/share/cayo/pkg-db/apt/ — apt lists/cache
• Creates the extension-release file at /usr/lib/extension-release.d/extension-release.cayo-pkg-db
• Exports just the sysext directory tree (no full OS)

FROM ghcr.io/frostyard/debian-bootc-core:latest AS build
# Run the same package installs as cayo to populate the DB
COPY build_files /ctx
RUN --mount=type=tmpfs,dst=/tmp /ctx/build

FROM scratch
COPY --from=build /var/lib/dpkg /usr/share/cayo/pkg-db/dpkg
COPY --from=build /var/lib/apt /usr/share/cayo/pkg-db/apt
COPY sysext/extension-release /usr/lib/extension-release.d/extension-release.cayo-pkg-db

2. sysext/extension-release (new)

ID=cayo
SYSEXT_LEVEL=1.0

This ties the sysext to the cayo OS ID. The ID must match the host's /etc/os-release ID field (set to cayo in build_files/build).

3. sysext/build-sysext.sh (new)

A script to build the sysext raw image from the container output:

• Extracts the container filesystem into a temporary directory
• Uses mksquashfs (or mkfs.erofs) to create cayo-pkg-db.raw
• The .raw file is what gets placed in /var/lib/extensions/ on the host

4. sysext/dpkg-db-query (new, optional)

A small wrapper script installed into /usr/bin/ inside the sysext:

#!/bin/bash
exec dpkg --admindir=/usr/share/cayo/pkg-db/dpkg "$@"

This gives users a convenient command to query the relocated DB without remembering the --admindir flag.

5. Justfile (modify)

Add recipes:

• build-pkg-db-sysext — builds the sysext container and produces the .raw image
• Possibly install-pkg-db-sysext — copies the .raw to /var/lib/extensions/ and runs systemd-sysext merge

6. .github/workflows/build.yml (modify)

Add a job (or step) to build and push the sysext image alongside the main image. The sysext .raw can be published as a GitHub Release artifact or as a separate OCI image tag (e.g., ghcr.io/frostyard/cayo:pkg-db-sysext).

7. build_files/build (minor modification)

The existing line 136-137 already saves a package list to /usr/share/cayo/server-packages.txt. No change strictly needed, but consider extracting the package list into a shared variable/file so that the sysext Containerfile can reference the same list without duplication.

Potential Risks and Edge Cases

1. DB/image version drift: The sysext's dpkg DB must be built from the same package set as the base image. If they get out of sync, the DB will show packages that aren't installed or miss ones that are. Mitigate by building both in the same CI run and tagging them together.

2. Superset DB (as noted in the issue): The issue acknowledges that the DB may list more packages than are actually installed on a given host if not all features are enabled. This is acceptable — document it clearly.

3. sysext path limitations: sysexts can only overlay /usr/ and /opt/. The dpkg database normally lives at /var/lib/dpkg/. Tools like dpkg -S won't automatically find the relocated DB. The wrapper script or documented --admindir usage is necessary.

4. apt functionality: Full apt operations (install/remove) won't work with a read-only relocated DB on an immutable system — this is by design. The sysext is query-only. Document this clearly.

5. Squashfs vs erofs: mksquashfs is widely available; erofs is newer and faster but less common. Default to squashfs.

6. Extension-release matching: If the ID or VERSION_ID in the sysext's extension-release doesn't match the host, systemd-sysext will refuse to merge. Need to ensure these stay in sync.

Suggested Order of Implementation

1. sysext/extension-release — trivial metadata file, establishes the sysext identity
2. sysext/Containerfile.pkg-db — the core build that captures the dpkg/apt DB into a sysext layout
3. sysext/dpkg-db-query — convenience wrapper script (included in the sysext)
4. sysext/build-sysext.sh — script to produce the .raw squashfs image from the container
5. Justfile — add build-pkg-db-sysext recipe
6. .github/workflows/build.yml — add CI job to build and publish the sysext
7. build_files/build — minor refactor if needed to share the package list

This fits comfortably in a single PR. The sysext is an additive feature with its own build path — no existing functionality is modified, and the risk of regression is minimal.