# Fedora bootc-image-builder Analysis ## Overview The Fedora bootc-image-builder is a containerized tool that creates bootable disk images from bootc (bootable container) inputs. It's specifically designed for Fedora/CentOS/RHEL systems using DNF/RPM package management and supports various output formats including QCOW2, AMI, VMDK, VHD, GCE, and ISO images. ## Architecture The tool follows a modular architecture with clear separation of concerns: 1. **Main Application** (`bib/cmd/bootc-image-builder/`) - Entry point and CLI handling 2. **Internal Libraries** (`bib/internal/`) - Core functionality for distro definitions and image types 3. **Data Definitions** (`bib/data/defs/`) - Distribution-specific package lists and configurations 4. **Build System** - Containerfile and build scripts for containerization ## File Structure Analysis ``` z fedora-bootc-image-builder/ ├── bib/ # Main application directory │ ├── cmd/ # Command-line applications │ │ ├── bootc-image-builder/ # Main application │ │ │ ├── main.go # Entry point, CLI setup, manifest generation │ │ │ ├── image.go # Image manifest creation logic │ │ │ ├── cloud.go # Cloud upload functionality (AWS) │ │ │ ├── mtls.go # mTLS configuration handling │ │ │ ├── partition_tables.go # Partition table definitions │ │ │ ├── workload.go # Workload-specific configurations │ │ │ └── *_test.go # Test files │ │ ├── cross-arch/ # Cross-architecture support │ │ │ └── canary.go # Cross-arch canary functionality │ │ └── upload/ # Upload utilities │ │ └── main.go # Upload command implementation │ ├── data/ # Data files and definitions │ │ └── defs/ # Distribution definitions │ │ ├── fedora-42.yaml # Fedora 42 package definitions │ │ ├── centos-9.yaml # CentOS 9 definitions │ │ ├── rhel-10.yaml # RHEL 10 definitions │ │ └── [other-distro].yaml # Other supported distributions │ ├── internal/ # Internal libraries │ │ ├── distrodef/ # Distribution definition handling │ │ │ ├── distrodef.go # Core distro definition logic │ │ │ └── distrodef_test.go # Tests │ │ └── imagetypes/ # Image type management │ │ ├── imagetypes.go # Image type definitions and validation │ │ └── imagetypes_test.go # Tests │ ├── go.mod # Go module dependencies │ └── go.sum # Go module checksums ├── build.sh # Build script ├── Containerfile # Container build definition ├── devel/ # Development tools and documentation │ ├── bootc-install # Bootc installation script │ ├── Containerfile # Development container │ ├── Containerfile.hack # Hack container for development │ ├── README.md # Development documentation │ └── Troubleshooting.md # Troubleshooting guide ├── test/ # Test suite │ ├── conftest.py # Test configuration │ ├── containerbuild.py # Container build tests │ ├── test_build_*.py # Various build tests │ ├── test_*.py # Other test modules │ └── vm.py # VM testing utilities ├── plans/ # Test plans │ ├── integration.fmf # Integration test plan │ └── unit-go.fmf # Go unit test plan ├── group_osbuild-osbuild-fedora.repo # OSBuild repository configuration ├── package-requires.txt # Required packages list ├── pytest.ini # Python test configuration ├── Makefile # Build automation ├── HACKING.md # Development guidelines ├── LICENSE # License file └── README.md # Main documentation ``` ## Key Components Analysis ### 1. Main Application (`main.go`) **Purpose**: Entry point and CLI interface **Key Features**: - Cobra-based CLI with commands: `build`, `manifest`, `version` - Container image inspection and size calculation - Manifest generation from container inputs - Progress reporting and logging - AWS cloud upload support - Cross-architecture building support **Hardcoded Values**: - Container size multiplier: `containerSizeToDiskSizeMultiplier = 2` (can be configurable) - Default distro definition paths (can be configurable) - Default image types and exports (can be configurable) - Fedora-specific manifest distro: `manifest.DISTRO_FEDORA` (Fedora-only) ### 2. Image Manifest Generation (`image.go`) **Purpose**: Core logic for creating OSBuild manifests **Key Features**: - Disk image and ISO manifest generation - Partition table creation with support for ext4, xfs, btrfs - Filesystem customization handling - Kernel options and boot configuration - User and group management - SELinux policy handling **Hardcoded Values**: - Default size: `DEFAULT_SIZE = uint64(10 * GibiByte)` (can be configurable) - Kernel options: `"rw"`, `"console=tty0"`, `"console=ttyS0"` (can be configurable) - Platform-specific configurations (BIOS, UEFI, etc.) (can be configurable) - Distribution-specific labels and configurations (Fedora-only) ### 3. Distribution Definitions (`distrodef.go`) **Purpose**: Load and manage distribution-specific package lists **Key Features**: - YAML-based package definition loading - Version matching (exact and fuzzy) - Image type-specific package sets - Support for multiple definition directories **Hardcoded Values**: - Definition file naming convention: `{distro}-{version}.yaml` (can be configurable) - Image type keys in YAML files (can be configurable) - Version comparison logic (can be configurable) ### 4. Image Types (`imagetypes.go`) **Purpose**: Define and validate supported image output formats **Key Features**: - Support for: ami, qcow2, raw, vmdk, vhd, gce, debian-installer, calamares - Export type mapping - ISO vs disk image validation - Cannot mix ISO and disk types in single build **Hardcoded Values**: - Image type to export mapping (can be configurable) - ISO flag for each image type (can be configurable) - Validation rules for image type combinations (can be configurable) ### 5. Distribution Data Files (`data/defs/`) **Purpose**: Store distribution-specific package lists and configurations **Structure**: ```yaml anaconda-iso: packages: - package1 - package2 # ... more packages ``` **Key Files**: - `fedora-42.yaml` - Fedora 42 package definitions - `centos-9.yaml`, `centos-10.yaml` - CentOS definitions - `rhel-9.yaml`, `rhel-10.yaml` - RHEL definitions - Various other distribution definitions ### 6. Container Build (`Containerfile`) **Purpose**: Multi-stage container build for the tool **Stages**: 1. **Builder**: Fedora 42 base, installs Go and dependencies, builds binary 2. **Runtime**: Fedora 42 base, installs runtime dependencies, copies binary **Hardcoded Values**: - Base image: `registry.fedoraproject.org/fedora:42` (Fedora-only) - Package repository: `group_osbuild-osbuild-fedora.repo` (Fedora-only) - Binary location: `/usr/bin/bootc-image-builder` (can be configurable) - Data location: `/usr/share/bootc-image-builder` (can be configurable) ## Package Management Integration The tool is deeply integrated with RPM/DNF ecosystem: 1. **DNF Solver**: Uses `dnfjson.Solver` for package dependency resolution 2. **RPM Metadata**: Caches RPM metadata in `/rpmmd` volume 3. **Librepo Support**: Optional librepo backend for faster downloads 4. **Repository Configuration**: Uses Fedora/CentOS/RHEL repositories ## Key Dependencies - **osbuild/images**: Core image building library - **osbuild/blueprint**: Configuration and customization handling - **containers/image**: Container image handling - **spf13/cobra**: CLI framework - **sirupsen/logrus**: Logging ## Debian-Specific Installer Options For the Debian version, we will replace Fedora's Anaconda installer with Debian-native options: ### 1. Debian Installer (debian-installer) - **Purpose**: Traditional Debian installation system - **Use Case**: Minimal, text-based installation - **Advantages**: Lightweight, fast, well-tested - **Package Requirements**: debian-installer packages, kernel, initramfs ### 2. Calamares - **Purpose**: Modern, graphical installer - **Use Case**: User-friendly installation with GUI - **Advantages**: Modern interface, flexible partitioning - **Package Requirements**: calamares, desktop environment packages Both options will be implemented as separate image types, similar to how the Fedora version handles `anaconda-iso`. ## Limitations and Hardcoded Values 1. **Distribution Support**: Only supports RPM-based distributions (Fedora, CentOS, RHEL) 2. **Package Manager**: Hardcoded to DNF/RPM 3. **Repository URLs**: Hardcoded Fedora/CentOS/RHEL repositories 4. **Container Registry**: Hardcoded to `quay.io/centos-bootc/` 5. **Default Configurations**: Many default values are hardcoded in Go source 6. **Architecture Support**: Limited to x86_64, aarch64, ppc64le, s390x, riscv64 7. **Installer System**: Anaconda is Fedora-specific and not applicable to Debian ## Configuration System The current configuration system uses: - **Blueprint format**: TOML/JSON configuration files - **Command-line flags**: Extensive CLI options - **Container metadata**: Extracts some configuration from container images - **Environment variables**: For AWS credentials and other settings ## Build Process 1. **Container Inspection**: Analyzes input container image 2. **Manifest Generation**: Creates OSBuild manifest 3. **Package Resolution**: Resolves dependencies using DNF 4. **Image Building**: Uses OSBuild to create final images 5. **Optional Upload**: Can upload to cloud providers (AWS) ## Testing Infrastructure - **Python-based tests**: Integration and functional tests - **Go unit tests**: Component-level testing - **Container testing**: Tests run in containers - **VM testing**: Can test resulting images in VMs - **Test plans**: FMF-based test organization This analysis provides the foundation for creating a Debian equivalent that adapts these concepts to the APT/DEB ecosystem while maintaining the same overall architecture and functionality.