bootc-docs/install/installation-flowchart.md

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.