# bootc Installation Process Flowchart ## High-Level Installation Flow ``` ┌─────────────────────────────────────────────────────────────────┐ │ bootc Installation Process │ └─────────────────────────────────────────────────────────────────┘ │ ▼ ┌─────────────────────────────────────────────────────────────────┐ │ Phase 1: Preparation │ ├─────────────────────────────────────────────────────────────────┤ │ 1.1 Container Environment Detection │ │ ├─ Check podman runtime │ │ ├─ Validate container execution info │ │ └─ Verify privileged access │ │ │ │ 1.2 Privilege and Namespace Validation │ │ ├─ Require --pid=host flag │ │ ├─ Validate host user namespace │ │ └─ Check root privileges │ │ │ │ 1.3 SELinux State Management │ │ ├─ Detect SELinux policy in container │ │ ├─ Check host SELinux state │ │ └─ Re-execute if needed for proper labeling │ └─────────────────────────────────────────────────────────────────┘ │ ▼ ┌─────────────────────────────────────────────────────────────────┐ │ Phase 2: Filesystem Setup │ ├─────────────────────────────────────────────────────────────────┤ │ 2.1 OSTree Repository Initialization │ │ ├─ Check for existing ostree/repo │ │ ├─ Run: ostree admin init-fs --modern . │ │ ├─ Configure repository settings │ │ └─ Set up stateroot │ │ │ │ 2.2 Container Image Deployment │ │ ├─ Prepare container image for pull │ │ ├─ Check disk space requirements │ │ ├─ Pull image into OSTree repository │ │ ├─ Deploy container to target filesystem │ │ └─ Set up deployment metadata │ └─────────────────────────────────────────────────────────────────┘ │ ▼ ┌─────────────────────────────────────────────────────────────────┐ │ Phase 3: Bootloader Setup │ ├─────────────────────────────────────────────────────────────────┤ │ 3.1 Bootupd Integration │ │ ├─ Detect target architecture │ │ ├─ Configure bootloader type │ │ └─ Install via bootupd │ │ │ │ 3.2 Architecture-Specific Bootloaders │ │ ├─ x86_64/aarch64: GRUB2 via bootupd │ │ ├─ s390x: zipl │ │ └─ Other: Platform-specific │ └─────────────────────────────────────────────────────────────────┘ │ ▼ ┌─────────────────────────────────────────────────────────────────┐ │ Phase 4: Kernel Configuration │ ├─────────────────────────────────────────────────────────────────┤ │ 4.1 Kernel Argument Processing │ │ ├─ Extract kargs from OSTree root │ │ ├─ Merge install config kargs │ │ ├─ Apply container image kargs.d │ │ └─ Add CLI-specified kargs │ │ │ │ 4.2 Initramfs Integration │ │ ├─ Locate kernel: /usr/lib/modules/$kver/vmlinuz │ │ ├─ Locate initramfs: /usr/lib/modules/$kver/initramfs.img │ │ └─ Configure bootloader entries │ └─────────────────────────────────────────────────────────────────┘ │ ▼ ┌─────────────────────────────────────────────────────────────────┐ │ Phase 5: Finalization │ ├─────────────────────────────────────────────────────────────────┤ │ 5.1 Filesystem Optimization │ │ ├─ Run: fstrim --quiet-unsupported -v /target │ │ ├─ Run: mount -o remount,ro /target │ │ └─ Run: fsfreeze -f /target && fsfreeze -u /target │ │ │ │ 5.2 Cleanup and Validation │ │ ├─ Close file descriptors │ │ ├─ Unmount target filesystem │ │ ├─ Close LUKS devices (if any) │ │ └─ Validate installation │ └─────────────────────────────────────────────────────────────────┘ │ ▼ ┌─────────────────────────────────────────────────────────────────┐ │ Installation Complete │ └─────────────────────────────────────────────────────────────────┘ ``` ## Detailed Installation Modes ### 1. to-disk Installation Flow ``` ┌─────────────────────────────────────────────────────────────────┐ │ bootc install to-disk │ └─────────────────────────────────────────────────────────────────┘ │ ▼ ┌─────────────────────────────────────────────────────────────────┐ │ 1. Validate Target Device │ │ ├─ Check if device is block device or file │ │ ├─ Handle loopback device if --via-loopback │ │ └─ Validate device permissions │ └─────────────────────────────────────────────────────────────────┘ │ ▼ ┌─────────────────────────────────────────────────────────────────┐ │ 2. Create Filesystem │ │ ├─ Determine filesystem type from config │ │ ├─ Run: mkfs.$fstype /dev/target │ │ └─ Set up partition table if needed │ └─────────────────────────────────────────────────────────────────┘ │ ▼ ┌─────────────────────────────────────────────────────────────────┐ │ 3. Mount and Deploy │ │ ├─ Mount: /dev/target /mnt │ │ ├─ Run: bootc install to-filesystem /mnt │ │ └─ Configure kernel arguments │ └─────────────────────────────────────────────────────────────────┘ │ ▼ ┌─────────────────────────────────────────────────────────────────┐ │ 4. Finalize │ │ ├─ Unmount: umount -R /mnt │ │ ├─ Close LUKS devices │ │ └─ Close loopback devices │ └─────────────────────────────────────────────────────────────────┘ ``` ### 2. to-filesystem Installation Flow ``` ┌─────────────────────────────────────────────────────────────────┐ │ bootc install to-filesystem │ └─────────────────────────────────────────────────────────────────┘ │ ▼ ┌─────────────────────────────────────────────────────────────────┐ │ 1. Validate Target Filesystem │ │ ├─ Check if target is directory │ │ ├─ Verify it's a mountpoint │ │ ├─ Detect if already OSTree system │ │ └─ Handle alongside installation │ └─────────────────────────────────────────────────────────────────┘ │ ▼ ┌─────────────────────────────────────────────────────────────────┐ │ 2. Clean Target (if needed) │ │ ├─ Wipe mode: Remove all contents │ │ ├─ Alongside mode: Clean boot directories │ │ └─ Default: Require empty root directory │ └─────────────────────────────────────────────────────────────────┘ │ ▼ ┌─────────────────────────────────────────────────────────────────┐ │ 3. Deploy Container Image │ │ ├─ Initialize OSTree repository │ │ ├─ Pull container image │ │ ├─ Deploy to target filesystem │ │ └─ Configure bootloader │ └─────────────────────────────────────────────────────────────────┘ │ ▼ ┌─────────────────────────────────────────────────────────────────┐ │ 4. Finalize │ │ ├─ Run: bootc install finalize │ │ ├─ Optimize filesystem │ │ └─ Validate installation │ └─────────────────────────────────────────────────────────────────┘ ``` ### 3. to-existing-root Installation Flow ``` ┌─────────────────────────────────────────────────────────────────┐ │ bootc install to-existing-root │ └─────────────────────────────────────────────────────────────────┘ │ ▼ ┌─────────────────────────────────────────────────────────────────┐ │ 1. Mount Host Root │ │ ├─ Mount: /:/target (if not already mounted) │ │ ├─ Detect existing OSTree system │ │ └─ Find physical root in /sysroot │ └─────────────────────────────────────────────────────────────────┘ │ ▼ ┌─────────────────────────────────────────────────────────────────┐ │ 2. Clean Boot Directories │ │ ├─ Remove existing bootloader configuration │ │ ├─ Clean /boot directory │ │ └─ Clean /boot/efi directory (if exists) │ └─────────────────────────────────────────────────────────────────┘ │ ▼ ┌─────────────────────────────────────────────────────────────────┐ │ 3. Deploy Alongside │ │ ├─ Initialize OSTree repository │ │ ├─ Deploy container image │ │ ├─ Configure bootloader │ │ └─ Set up cleanup service │ └─────────────────────────────────────────────────────────────────┘ │ ▼ ┌─────────────────────────────────────────────────────────────────┐ │ 4. Setup Cleanup │ │ ├─ Create bootc-destructive-cleanup.service │ │ ├─ Configure for first boot cleanup │ │ └─ Preserve existing data in /sysroot │ └─────────────────────────────────────────────────────────────────┘ ``` ## Error Handling Flow ``` ┌─────────────────────────────────────────────────────────────────┐ │ Error Detection │ └─────────────────────────────────────────────────────────────────┘ │ ▼ ┌─────────────────────────────────────────────────────────────────┐ │ 1. Validation Errors │ │ ├─ Container environment issues │ │ ├─ Privilege/permission errors │ │ └─ SELinux policy conflicts │ └─────────────────────────────────────────────────────────────────┘ │ ▼ ┌─────────────────────────────────────────────────────────────────┐ │ 2. Resource Errors │ │ ├─ Insufficient disk space │ │ ├─ Memory allocation failures │ │ └─ File descriptor limits │ └─────────────────────────────────────────────────────────────────┘ │ ▼ ┌─────────────────────────────────────────────────────────────────┐ │ 3. Deployment Errors │ │ ├─ Container image pull failures │ │ ├─ OSTree repository issues │ │ └─ Bootloader installation failures │ └─────────────────────────────────────────────────────────────────┘ │ ▼ ┌─────────────────────────────────────────────────────────────────┐ │ 4. Recovery Actions │ │ ├─ Rollback OSTree deployment │ │ ├─ Restore bootloader configuration │ │ └─ Clean up partial installation │ └─────────────────────────────────────────────────────────────────┘ ``` ## External Command Dependencies ### Required Commands - `ostree` - OSTree repository management - `bootupd` - Bootloader management - `podman` - Container runtime - `fstrim` - Filesystem optimization - `mount`/`umount` - Filesystem mounting - `fsfreeze` - Filesystem freeze/thaw ### Optional Commands - `cryptsetup` - LUKS encryption - `grub2-mkconfig` - GRUB configuration - `dracut` - Initramfs generation - `mkfs.*` - Filesystem creation This flowchart provides a comprehensive view of the bootc installation process, showing the sequential phases, decision points, and error handling paths.