Skip to main content

index

bootc-installer

Graphical installers that put a bootc container image on a disk.
One backend, five desktop frontends, your brand.


bootc-installer installs an operating system that ships as a bootc container image. A wizard asks for a disk, an encryption mode and a user account. Then the fisherman backend partitions the disk, installs the image and prepares the first boot.

The GNOME installer, screen by screen

Why you need it​

A bootc image is a container image that boots. You build it with a Containerfile, and you update a computer with bootc upgrade. But a container image is not on a disk until something puts it there.

bootc has commands for that step: bootc install to-disk and bootc install to-filesystem. They are command-line tools for an administrator. A person who downloads your live ISO needs more than a command:

  • A wizard in the style of the desktop that the ISO starts.
  • A check that the computer has enough RAM, a usable disk and UEFI.
  • Disk encryption with a passphrase or the TPM, and a recovery key.
  • A user account and a hostname.
  • A progress bar, a log when the install fails, and a restart button.
  • An install with no network, from the image on the ISO.

bootc-installer supplies these parts. You supply the image.

Who it is for​

You areYou get
The builder of a bootc imageAn installer for your live ISO. You set the name, the artwork, the text and the image catalog in /etc/bootc-installer/. You do not fork the code. Refer to Customise the installer for your image.
The maintainer of a desktop spinA frontend in the toolkit of your desktop: GNOME, KDE Plasma, COSMIC, Niri or XFCE. All five drive the same backend with the same recipe.
A person with a computerThe installer on the live ISO of your distribution. You can also run it as a Flatpak on a Linux system that you have now.
An administratorAn unattended install from a JSON recipe. Refer to Recipes and autoinstall.

[!WARNING] An install erases the disk that you select. Make a backup of your data before you start. The confirm screen shows the disk and the data that the install removes.

Install​

curl -Lo installer.flatpak \
https://github.com/tuna-os/bootc-installer/releases/latest/download/org.bootcinstaller.Installer.flatpak \
&& sudo flatpak uninstall -y org.bootcinstaller.Installer org.bootcos.Installer 2>/dev/null; sudo flatpak install --bundle -y installer.flatpak
flatpak run org.bootcinstaller.Installer

For the devel build and a tour of each screen, refer to Install and use the installer.

Features​

  • Two boot stacks. systemd-boot with composefs for sealed images such as Dakota. GRUB2 for images such as Bluefin and Bazzite. The partition layout follows the boot stack.
  • Disk encryption. LUKS2 with a passphrase, with the TPM2, or with the two together. For a TPM-only install, the installer shows a recovery key and holds the restart until you confirm it.
  • An image catalog. Each frontend lists the images in fisherman's catalog, or in the catalog that your ISO ships.
  • A user account, when the image needs one. The account is an administrator.
  • A hardware check. The installer reads RAM, CPU, UEFI, TPM and disks from fisherman probe, and tells you what does not qualify.
  • Offline install. On a live ISO, the installer uses the image on the media and does not use the network.
  • Fast first boot. The backend copies the Wi-Fi and Bluetooth setup from the live session, and fills the caches.
  • Your brand. A branding.json file sets the product name, the text and the artwork. The code has no product name.
  • Unattended install (GNOME and XFCE). --autoinstall reads a JSON recipe and does not show the wizard.
  • A phone companion (GNOME, COSMIC and XFCE). Scan a QR code and type your account data on a phone.

The frontends do not have all features yet, and some features have open defects. docs/PARITY.md shows what each frontend does and links the issues. The installer does not set the language, the keyboard layout or the time zone of the new system yet.

How it works​

frontend (wizard) ──recipe JSON on stdin──▶ fisherman (root) ──▶ disk
▲ │
└──────── progress as JSON lines ────────────┘
  1. The frontend asks fisherman probe --json for the disks and the hardware.
  2. The frontend checks each field with fisherman validate while you type.
  3. The frontend writes the recipe to the standard input of fisherman. No file holds the recipe, because the recipe contains the passphrase and the password.
  4. fisherman partitions the disk, encrypts it, runs bootc install to-filesystem and configures the new system.
  5. The frontend shows the progress, then the recovery key and the restart button.

In a Flatpak, the frontend starts fisherman on the host with flatpak-spawn --host pkexec. How an install works gives each step.

Guidebook​

The guidebook has the full documentation:

PageContents
Install and use the installerProduction and devel builds, and the wizard screen by screen
How an install worksBoot stacks, the install steps, encryption and first boot
Recipes and autoinstallRecipe examples, field reference and unattended install
Customise the installer for your imageYour own catalog and defaults in /etc/bootc-installer/, and new catalog images
Build, test and releaseBuild, demo mode, tests, screenshots and the release flow

Frontends​

This repository holds all five frontends. They share the fisherman backend, the recipe schema and the screen contract in shared/. CI renders all five frontends in docs/walkthrough/.

On a live ISO, each frontend starts fisherman on the host. The file /etc/bootc-installer/live-iso-mode tells fisherman that the image is on the media. fisherman then checks the image on the media before it reads a disk or uses the network. docs/live-iso.md tells you how to build such an ISO.

fisherman is a git submodule. Every Flatpak builds fisherman from that submodule, so the gitlink is the only pin. The four frontend manifests use the shared module shared/flatpak/fisherman.json. Renovate keeps the gitlink current. To move it by hand, run shared/ci/fisherman_pins.py.

FrontendPathToolkitWalkthrough
GNOMEbootc_installer/GTK4 / libadwaita (Python)docs/gui-walkthrough.md
KDE Plasmafrontends/kde/Qt 6 / Kirigamifrontends/kde/docs/gui-walkthrough.md
COSMICfrontends/cosmic/libcosmic (Rust)frontends/cosmic/docs/gui-walkthrough.md
Nirifrontends/niri/Quickshell QML + Gofrontends/niri/docs/gui-walkthrough.md
XFCEfrontends/xfce/GTK3 / PyGObjectfrontends/xfce/docs/gui-walkthrough.md

CI moves a release from dev to prod when all checks pass: docs/RELEASE.md. For the merge of the old repositories, refer to docs/MIGRATION.md.

Contribute​

Read the contribution guide and Build, test and release. Open pull requests against dev.

Contribute compute — no code needed​

Donate time with your AI CLI.

Your machine runs one task at a time using your signed-in AI coding CLI. The relay alternates between eligible School (OS) and Reef (apps) hives after each task. If one hive has no work, the other can continue.

The guide covers prerequisites, verified just setup, credentials, provider costs, and how to stop with Ctrl+C. Your subscription quota or API charges apply. Never post account credentials or API keys in issues or pull requests.