RTFM · Image Creator

The Saphira Image Creator.

One command builds Saphira Linux disk images and installs them onto physical disks: BIOS and UEFI boot, OpenRC and systemd inits, raw and QCOW2 formats, virtual disks and real hardware. This is working software, proven by a SaphiraD install booting on a physical UEFI machine, not a roadmap.

← RTFM home

What it does

The image creator owns the target matrix, the partition plan, the bootloader invocation, init-system preparation and measurement. It assembles through the canonical path (saphira-install and saphira-assemble-rootfs) and reads dependency closure from APK metadata. It never unpacks an APK, never writes a package list of its own, and never substitutes its own installer. A target is a row in a data file, not a new implementation.

list-targets: print the supported target matrix.
plan: print the exact partition plan for a target. Needs no privileges and no repository.
report: resolve the profile closure statically and report package counts and sizes. Builds nothing.
build: partition an image, install Saphira, prepare init, install the bootloader, report what went in.
install-to-disk: the same engine aimed at a whole physical disk instead of an image file.
export: pack a finished image's root filesystem into a distributable bootstrap tarball plus checksum.

Start with Targets to pick a row, Build for image files, Install to disk for physical hardware, First boot for what happens on first power-on, and the CLI reference for every option.

Why any of this needs a tool

You could partition, format, mount, install packages and install a bootloader by hand; nothing stops you, and nothing clever sneaks into the tool either: it runs the same kinds of steps you would run. What it adds is the death of silent assumptions. A UUID typo or a missing ESP otherwise surfaces only as an unbootable machine, exactly when you least want a mystery; here the plan is generated from data, every identity decision is printed as visible reconciliation, and the build ends with a report of what went where. The first machine is repeatable only because nothing depended on luck the second time round.

Proven, then announced

The uefi-saphirad target, the full SaphiraD product image for UEFI, builds end to end and has been installed and booted on physical UEFI hardware. A 2 GiB demonstration build assembles 61 packages into a 358 MiB rootfs, installs the GRUB EFI payload, and reports exactly what went in. That is the basis for this documentation: observed behaviour, not planned behaviour.

sudo saphira-image build \
  --target uefi-saphirad \
  --output /imagebuilder/saphirad-demo.qcow2 \
  --size 2G

Build output carries honest noise. Lines such as ensure-identity: ... skipping non-identity sysusers line mean only explicitly pinned user and group identities are replayed into the offline image; the rest are created by their packages at runtime. That is expected behaviour, not a defect, and it does not hurt the image at all.

Installer media today, provisioning image next

Two things that sound alike and are not the same. The usb-installer target exists today: a hybrid BIOS/UEFI medium that boots into a text-menu installer and installs Saphira onto the machine, choosing the installed system's init in the menu. It is installer media you build yourself.

The approximately 500 MB bootable USB and hypervisor provisioning image is the next chapter: a ready-made distributable built on this same engine. It is coming next; it is not released, and nothing here asks you to wait for it. Everything documented in this section works with the tool as shipped.