# 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.
