debian-bootc

Simplify and Innovate for Everyone.

Identify gaps and fill them, make improvements where possible, but above all, empower developers to offer more to users.

debian-bootc builds Debian 13 as a bootc/OSTree operating-system image. It packages the bootc stack that is not provided by Debian, assembles OCI images, boots them under QEMU for runtime validation, and generates installer artifacts.

The repository is under active development. The amd64 path is the current installation target; arm64 image, package, and disk-image work is present in the pipeline but should be treated as being validated until the architecture matrix is explicitly released.

• Debian packages for bootc, OSTree, composefs, bootupd, a BLS-capable GRUB build, first-boot setup, and bootc-specific service integration.
• A signed APT repository published from the package manifest in workflows/bootc-debs-builder/packages.yml.
• A full image and a reduced minimal image assembled from Debian Trixie.
• Native amd64 and arm64 jobs in the shared CI, content-addressed package reuse, GHCR publication, and keyless cosign signing.
• Boot tests that install an image to a virtual disk, start it with QEMU/KVM, and execute workflows/image-tests/tests.yml over SSH before publication.
• Online and offline amd64 installer ISOs.
• Optional raw image generation for the targets enabled by the caller workflow.

The minimal Containerfile declares both automatic-update and lock variants. The CI publishes architecture-specific tags and then creates manifest-list tags after successful builds.

The repository's pipeline.yml is a thin caller for DaemonCores-CI:

1. build the package environment;
2. build amd64 and arm64 Debian packages in dependency waves;
3. publish the signed APT repository;
4. build every root-level Containerfile* variant;
5. boot and test each image before it is pushed;
6. sign published images and assemble multi-architecture manifests;
7. build the selected installer and disk-image artifacts.

Pushes use change detection to skip unaffected stages. A scheduled run performs a full rebuild on the first day of each month. Manual runs expose stage-selection inputs.

The full image can be assembled on an amd64 host with:

podman build --format docker \
  --build-arg PRODUCT_NAME="debian bootc" \
  -f Containerfile \
  -t debian-bootc:local .

The build downloads the repository signing key, verifies its pinned SHA-256 digest, and consumes packages from the project's APT repository. See docs/minimal.md for the minimal image's architecture-specific arguments.

When a successful install-iso release is available, use the online ISO for a registry-backed installation or the offline ISO when the image must be embedded in the installation media.

The installer performs its own interactive target-disk selection and uses bootc install to-filesystem. It creates EFI and /boot partitions plus a Btrfs pool with separate root, var, and varlog subvolumes. Reinstallation can preserve the existing var subvolume.

The installer is destructive to the selected disk. Review the prompt carefully and test in a virtual machine before using it on physical hardware.

GitHub Pages must be configured for Actions deployment so the APT repository can be published.

• Architecture
• Design decisions and security trade-offs
• Minimal image
• Support
• Security policy

Made with ⭐ by the DaemonCores community