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.
The two repos. margine-image
is the build pipeline: Containerfile, staged build scripts, CI workflows,
installer and live-ISO configs — the repo that produces the OCI image.
margine-fedora-atomic
is the spec: declarations, branding assets, ADRs. When a snippet's path starts
with build_files/, live-env/, installer/ or .github/workflows/, it
lives in margine-image; assets/, declarations/ and docs/adr/ paths
live in the spec 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, o……
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 a……
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-part……
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 (C……
The handbook is also maintained as a single markdown document in margine-fedora-atomic. Day-to-day usage docs live in the wiki.