Bootloader Implementation

Bootloader Implementation

This document details the engineering decisions behind Apollo OS's bootloader installation process, specifically the shift from bootupd to a native bootctl approach.

Background Context

By default, the bootc utility delegates bootloader installation and configuration to a backend service called bootupd. However, bootupd was primarily designed for Fedora-based systems and expects specific bootloader binaries and cryptographic signatures (e.g., shim for Secure Boot).

Apollo OS is based on Arch Linux, which ships standard, unsigned systemd-boot EFI binaries (systemd-bootx64.efi).

Technical Challenges with bootupd

During development, integrating Arch Linux's systemd-boot with bootupd proved incompatible:

1. Metadata Generation Failures: Running bootupctl backend generate-update-metadata within the build environment resulted in internal assertion panics (assertion failed: efi_components.len() > 1).
2. Path Hardcoding: System tracing (strace) revealed that bootupd is strictly hardcoded to search for EFI components in paths specific to Fedora OSTree deployments, rejecting generic Arch Linux EFI structures.
3. Previous Workarounds: Initial attempts to bypass this involved creating placeholder GRUB configurations in the Containerfile. While this allowed the build to pass, it resulted in empty EFI partitions during hardware installation, rendering the system unbootable.

The Native Implementation

To ensure a robust and reliable boot sequence, Apollo OS completely bypasses the incompatible bootupd implementation in favor of a native approach.

The Current Workflow:

1. Container Cleanup: All placeholder bootloader configurations and bootupctl commands have been removed from the Containerfile to maintain image purity.
2. Bootc Delegation: During installation, the Alga installer explicitly instructs bootc to skip bootloader management by passing the --bootloader none argument.
3. Native Installation: Immediately after bootc successfully deploys the root filesystem, the Alga installer assumes control. It dynamically locates the EFI System Partition (via GUID c12a7328-f81f-11d2-ba4b-00a0c93ec93b), mounts it, and executes the native bootctl install --esp-path=... command.

Result: Apollo OS utilizes a pure, native systemd-boot implementation that fully complies with the Boot Loader Specification (BLS) and integrates seamlessly with OSTree deployments without relying on fragile workarounds.