Handbook · 12 chapters · ~40k words
Building an atomic Linux distribution.
This handbook documents, end to end, how Margine is built, and doubles as a generic guide to building a bootc-based atomic distribution. It is written from the real code: every snippet is quoted from the repos that produce the OS people boot, with the file path as caption.
One repo. Everything lives in margine-image:
the build pipeline (Containerfile, staged build scripts, CI workflows,
installer and live-ISO configs) and the spec it consumes (declarations,
branding assets, ADRs). Snippet paths are repo-relative: build_files/,
live-env/, installer/ and .github/workflows/ are the pipeline;
build_files/40-spec-scripts/ holds the vendored scripts and declarations,
build_files/50-branding/assets/ the branding, and docs/spec/ the
specification docs and ADRs. (An earlier split kept the spec in a separate
margine-fedora-atomic repo. It was merged in and archived on 2026-07-05,
so the build no longer fetches anything: every path a snippet cites is in
this one repo.)
Conventions. Chapters build on each other but are readable standalone. Every chapter ends with an Alternatives & other distros section (the other viable ways to solve the same problem and who uses them) because most decisions here are trade-offs, not truths. Real production incidents appear as Lesson boxes (symptom → root cause → fix). Commands shown against the running system assume a bootc host; commands in build context run inside the image build.
The atomic, image-based OS model
Margine is not "a Fedora with packages preinstalled". It is an OCI container image that boots. The running system is a read-only checkout of that image; updat……
Anatomy of the image repo
A bootc distro is, at its core, one git repo that produces one OCI image. For Margine that repo is margine-image. This chapter walks its layout, the Container……
Replacing the kernel in an atomic image
The kernel is just files in the image: /usr/lib/modules/<kver>/vmlinuz, the module tree next to it, and an initramfs.img in the same directory. In a bootc ima……
Secure Boot for a custom kernel: shim → MOK
Chapter 3 swapped Bluefin's stock kernel for CachyOS. That swap breaks exactly one link in the…
Shipping desktop opinion as data
An atomic image is more than packages: most of what makes a distro _feel_ like a distro is configuration: default settings, extensions, boot splash, logos, on……
Application payload: Flatpaks and the offline-docs module
The OCI image owns /usr. Apps live in /var/lib/flatpak, and ostree/bootc reset /var per deployment: anything you put there in the Containerfile is silently ab……
Rechunking: shipping a 14 GB OS as reusable chunks
The build so far produces a working bootc image. This chapter is about making it…
Supply chain: cosign signing, host verification, and pinning
A bootc distro is a pipeline that turns a Git push into a root filesystem on someone's laptop. Every hop in that pipeline (GitHub Actions runners, third-party……
CI/CD for an OS: GitHub Actions as the build farm
An atomic distro's "release engineering" is a container pipeline. Margine ships from three workflows in margine-image/.github/workflows/:…
Getting the image onto metal: installers and ISOs
A bootc image is an OCI artifact. Registries deliver upgrades; they do not deliver the _first_ install. Something has to partition a disk, lay down an ostree……
Shipping and day-2 operations
A bootc distro has two delivery products: the OCI image (the thing installed systems track daily) and the install media (the thing new users download once). T……
Trust but verify: validators, diagnostics, and the lesson catalog
An atomic distro's promise, "the image you tested is the image you run", is only as good as the testing. Margine validates at three altitudes: build time (CI……
The handbook is also maintained as a single markdown document in margine-fedora-atomic. Day-to-day usage docs live in the wiki.