zfs-aurora-complex

Why This Repo Exists

Fedora-family images move kernels quickly, and ZFS is an out-of-tree kernel module — so a new Fedora kernel can land before a matching OpenZFS release exists. Build that carelessly and you publish an Aurora DX image whose kernel and ZFS modules do not match.

This repository builds a signed Aurora DX image with ZFS userspace and kernel modules installed from a self-hosted akmods cache image (a container image holding prebuilt ZFS kernel-module packages), Distrobox and Homebrew inherited from upstream Aurora DX, and a single-repository signing policy for signed bootc upgrade. It deliberately stays close to standard tooling: one Containerfile, direct buildah/Open Container Initiative (OCI) build arguments, one image repository (ghcr.io/danathar/zfs-aurora-complex), and one shared akmods cache repository (ghcr.io/danathar/zfs-aurora-complex-akmods).

OpenZFS is not hand-pinned to a patch version. Each build resolves the newest stable release in a configured minor line (ZFS_MINOR_VERSION, 2.4 by default — see ci/defaults.json) from OpenZFS's own GitHub releases at build time, and that is the version it attempts to build and install.

Important

Changing this repository is a production change, not a demonstration. A bad build can break a booted machine and put pooled data at risk, so the build, promotion, and signing paths are held to a production standard — understand the blast radius before changing them. AI agents working here must read CLAUDE.md first.

Note

Developed with significant AI assistance. For a simpler, more direct approach to the same problem, see aurora-zfs-simple — the minimal expression of the same idea. This repo is the one the author daily-drives, and carries the fuller pipeline: candidate-first promotion, input pinning, digest resolution, shared akmods caching, image signing, and unit tests throughout.

Install

Warning

This is a single-maintainer image stream. It is production for its author -- daily-driven on real hardware with real ZFS pools -- but the bar it has cleared is "safe enough for one person's own machines", not a vendor support commitment. CI does not boot the image or import a pool before :latest moves; promotion proves the image composed, is correctly signed, and passed bootc container lint, nothing more. The recovery model is image rollback, not pre-publication runtime testing -- see docs/safety-model.md. Switching a machine you depend on onto this image means trusting that bar, not a guarantee.

sudo bootc switch --enforce-container-sigpolicy ghcr.io/danathar/zfs-aurora-complex:latest
sudo systemctl reboot

--enforce-container-sigpolicy is required on the first switch, not optional -- it records the deployment as policy-verified instead of as an unverified registry image. Afterwards, sudo bootc upgrade is the normal path.

Full steps, post-boot validation commands, and manual signature verification: docs/install-and-verify.md.

Documentation

Start here depending on what you want:

I want to...	Read
run this image on a machine	docs/install-and-verify.md
know what this promises, and what to do when a build is bad	docs/safety-model.md
build or fork it myself	docs/building-locally.md
understand the design	docs/architecture-overview.md
find my way around the code	docs/code-reading-guide.md
understand image signing and bootc trust	docs/signing-and-bootc.md
fix a broken build	docs/upstream-change-response.md
read the deep design history and validation notes	docs/design-deep-dive.md
change which akmods commit is built	docs/akmods-fork-maintenance.md
submit a change	CONTRIBUTING.md, and tests/e2e/README.md for the CLI end-to-end tests
know how much scrutiny a change gets, and how it is reviewed	docs/risk-tiers.md, docs/review-rubric.md
read what the badges, gates and numbers mean	docs/quality.md, docs/metrics.md
work with an AI agent here, or judge its output	docs/SECURITY-AI.md, docs/agent-boundaries.md, docs/multi-agent.md, docs/ai-ops-runbook.md
run a recurring agent procedure, or trace a change to its task	.github/prompts/README.md, .claude/commands/README.md, docs/agent-tasks/README.md
see how main is protected	docs/branch-protection.md
learn from past incidents, and see where the project is headed	docs/reflections/, docs/strategy.md
see which pins and decisions need a human later, and why main and runtime testing are set up as they are	docs/maintenance-watchlist.md, docs/production-boundary-proposal.md, docs/runtime-validation-proposal.md
look up a term	docs/glossary.md
see the whole documentation map	docs/documentation-guide.md

The CDDL/GPLv2 position on redistributing a binary ZFS module is recorded in docs/licensing.md. It is not legal advice; read it before redistributing this image or basing a downstream image on it.

About this project

Note

This project was developed with significant AI assistance and should be treated cautiously. Read its output the way you would read any unreviewed contribution.

It is a third-party image built on ghcr.io/ublue-os/aurora-dx (see Containerfile). It is not an official Universal Blue or Aurora image, is not an official Fedora image, and is not affiliated with OpenZFS.

It is provided as-is, with no promise that it is safe for your machines, your pools, or your data. docs/safety-model.md states what this pipeline actually proves and what it does not.

Maintained with Hive (ACMM L6)

Maintenance is assisted by Hivecommons Hive at ACMM level 6 (Fully Autonomous). The repository is maintained by @Danathar.

What L6 permits here:

• Agents file issues and open pull requests, and agent pull requests merge once their required checks pass unless they carry hold. Merging to main publishes a signed image, so those checks are the gate. docs/branch-protection.md lists the required checks and docs/risk-tiers.md says which changes need a human.
• The reviewer agent backs each finding with a file and line and never merges, approves or closes a pull request.
• Labels carry approval authority and automation must never apply one. See Labels carry authority in docs/SECURITY-AI.md.

Learn more: Hive · Hive Hub · ACMM levels · full ACMM policy matrix

References

• Danathar/aurora-zfs-simple: https://github.com/Danathar/aurora-zfs-simple (simpler approach to the same problem)
• ublue-os/brew: https://github.com/ublue-os/brew
• OpenZFS releases: https://github.com/openzfs/zfs/releases