Saphira Image Creator

Saphira Image Creator: From source packages to bootable systems

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

What it does

Saphira Image Creator is one command family that builds Saphira Linux disk images and installs them onto physical disks. It covers BIOS and UEFI boot, OpenRC and systemd inits, raw and QCOW2 image formats, and both virtual machines and real hardware. It is working software, proven by a SaphiraD system booting on physical UEFI hardware, not a roadmap.

list-targets: print the supported target matrix, with no privileges and no repository needed.
plan: print the exact partition plan for a target; inspect it on a machine that could never build an image.
report: resolve the composed profile against the repository and report what would be installed, without building.
build: partition an image, install Saphira, prepare the init system, install the bootloader, and 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 with a checksum.

The architecture is deliberately small. Profiles define the intended system; the package manager resolves the dependency closure; the image creator handles partitioning, filesystems, installation and bootloader configuration. One image creator, multiple boot methods, multiple init systems, virtual machines and physical hardware.

Supported targets

A target is a row in a data file: a boot method, an init system and a profile. Assembly is common; only the partition plan, the bootloader invocation and the init preparation differ.

saphira-image list-targets
# TARGET            BOOT    INIT       PROFILE
# bios-openrc       bios    openrc     minimal-openrc
# bios-systemd      bios    systemd    minimal-systemd
# bios-saphira      bios    openrc     saphira-openrc
# bios-saphirad     bios    systemd    saphirad-systemd
# uefi-openrc       uefi    openrc     minimal-openrc
# uefi-systemd      uefi    systemd    minimal-systemd
# uefi-saphira      uefi    openrc     saphira-openrc
# uefi-saphirad     uefi    systemd    saphirad-systemd
# usb-installer     hybrid  systemd    usb-installer

Noteusb-installer is installer media, not an installed system: it boots BIOS and UEFI into a text-menu installer and install-to-disk refuses it. Build produces raw (.raw) or QCOW2 (.qcow2) images; other formats get their own sections once their implementation status is confirmed.

Build virtual machine images

build partitions an image and installs Saphira through the canonical installer, then reports what went in. A .raw suffix produces a raw image; .qcow2 converts through qemu-img (qemu required). An existing output path is refused, never overwritten.

saphira-image build
  --target uefi-saphirad
  --output saphira.qcow2
  --size 8G

Adjust --size, --allocate, --esp-size and --root-size to size the layout; the remainder can be left unallocated for later growth. --arch selects x86_64 or aarch64.

Install onto physical disks

install-to-disk runs the same engine onto a real disk instead of an image file: the same partition generator, installer, identity replay and PARTUUID-stable bootloader. Only the backing differs.

sudo saphira-image install-to-disk
  --target uefi-saphirad
  --device /dev/nvme0n1
  --esp-size 128
  --allocate 64G
  --boot-size 256
  --swap-size 16G
  --hostname minimer.vm2.uk

The installation on minimer.vm2.uk used exactly this command. The plan it printed first:

partition plan:
  label: gpt
  # UEFI+boot: ESP the firmware reads, separate ext4 /boot, then root.
  start=2048, size=262144, type=EFI, name="esp"
  start=264192, size=524288, type=Linux, name="boot"
  start=788480, size=99876864, type=Linux, name="root"
  start=100665344, size=33554432, type=swap, name="swap"
firmware: UEFI, 128 MiB FAT32 ESP, GRUB x86_64-efi --removable
filesystem: ext4 root (label saphira-root)
bootloader: grub-install to /dev/nvme0n1 (the disk, never a partition)

After installation the report confirmed: Linux 7.2.3, systemd 262, 66 packages installed, rootfs 1492 MiB. The machine rebooted into the installed system and was reached over SSH.

Installation safeguards

Warninginstall-to-disk NEVER guesses a device: there is no default, no discovery and no --yes. The plan is always printed first, and you must type the device path back to confirm destruction of everything on it. A device is refused outright when it does not exist, is not a block device, has any mounted partition or active swap, or hosts the running system. --preview prints the complete plan and touches nothing.

Use --preview to review the layout before committing. Nothing resizes or overwrites silently; over-budget size combinations are refused.

Proven on physical hardware

This is not a virtual-machine demonstration. The uefi-saphirad target, the full SaphiraD product image for UEFI, was installed onto physical hardware and booted:

Samsung 970 EVO Plus 500 GB NVMe.
GPT with separate EFI, /boot, root and swap partitions.
Linux 7.2.3, systemd 262.
GRUB UEFI bootloader (x86_64-efi, removable).
Rebooted into the installed system and accessed over SSH.
Approximately 1.5 GiB used on the root filesystem.

NoteThe successful installation logs substantiate every claim on this page. No inflated promises, no pretend demonstrations.

Source and packages

Saphira Image Creator ships as the saphira-image-creator package (BUSL-1.1) and is built from the Saphira recipe tree. The implementation, the target matrix, the partition generator and the installer invocation, is the authority for what the tool does.