deb-bootc-image-builder-new/docs/debian-installer.md

Debian Installer Integration

Overview

This document explores how to integrate debian-installer (d-i) support into the debian-bootc-image-builder project, examining the traditional debian-installer build process and potential integration approaches.

Traditional Debian Installer Build Process

Core Toolchain

The official debian-installer is built using a structured toolchain:

• Primary Tool: Makefile in debian-installer/build/ directory
• Build System: Make-based with structured targets and dependencies
• Dependencies: Listed in installer/debian/control file
• Environment: Requires Debian unstable (sid) or sid chroot

Directory Structure

debian-installer/
├── build/
│   ├── Makefile          # Main build orchestrator
│   ├── util/             # Helper scripts
│   ├── config/           # Build targets per architecture
│   ├── pkg-lists/        # udeb packages for each image type
│   ├── boot/             # Boot configuration files
│   └── localudebs/       # Custom udebs not in standard mirror

Key Components

• udebs: Debian Installer packages (specialized for installer environment)
• pkg-lists: Define which udebs are included in each image type
• config: Architecture-specific build targets and supported media types
• boot: Bootloader configuration for different boot methods

Build Process

1. Setup: Ensure build dependencies are satisfied
2. Targets: Use make commands like build_cdrom_isolinux, build_netboot
3. Cleanup: Run make reallyclean between builds

Alternative Tools

simple-cdd

• Purpose: Create custom Debian installation CDs
• Approach: Configuration-driven, uses debian-installer as base
• Use Case: Custom distributions, pre-configured installs
• Advantage: Simpler than full d-i build system

debian-cd

• Purpose: Official Debian CD/DVD creation
• Approach: Complex build system for official releases
• Use Case: Official Debian releases
• Complexity: High, designed for official distribution

Integration Approaches

Option 1: Hybrid Approach (Recommended)

• Disk Images: Use OSBuild (qcow2, ami, vmdk, raw)
• debian-installer: Use simple-cdd integration
• Shared Configuration: Leverage existing .config/registry.yaml system

Advantages:

• Uses each tool for its intended purpose
• OSBuild excels at disk images
• simple-cdd is proven for installer creation
• Maintains project focus and simplicity

Option 2: OSBuild Extension

• Approach: Extend OSBuild with debian-installer stages
• Complexity: High - requires OSBuild modifications
• Maintenance: Ongoing OSBuild integration work

Option 3: Focus on Disk Images Only

• Approach: Remove installer support entirely
• Focus: Pure disk image creation with OSBuild
• Simplicity: Maximum focus and maintainability

Implementation Strategy

Recommended: simple-cdd Integration

1. Add debian-installer command:

   debian-bootc-image-builder installer --type debian-installer
   

2. Configuration Integration:

   • Extend .config/registry.yaml with installer settings
   • Support debian-installer specific configurations
   • Maintain consistency with existing config system

3. Build Process:

   • Use simple-cdd for installer creation
   • Integrate with existing container workflow
   • Leverage existing APT integration

4. Package Management:

   • Use existing APT solver for udeb resolution
   • Extend package definitions for installer packages
   • Maintain consistency with disk image approach

Comparison: Fedora vs Debian Approach

Fedora (anaconda)

• OSBuild Integration: Native support via org.osbuild.anaconda stage
• Package-Based: Uses RPM packages in YAML definitions
• Pipeline: Multi-stage OSBuild pipeline (build → anaconda-tree → bootiso)
• Configuration: Blueprint format with anaconda module support

Debian (debian-installer)

• Traditional Toolchain: Make-based build system
• Package-Based: Uses udeb packages (installer-specific)
• Alternative Tools: simple-cdd, debian-cd
• Configuration: Various formats (simple-cdd config, debian-cd config)

Recommendation

Use the Hybrid Approach with simple-cdd integration:

1. Keep OSBuild for disk images - it's designed for this purpose
2. Use simple-cdd for debian-installer - proven, maintained tool
3. Share configuration system - extend .config/registry.yaml
4. Maintain consistency - use existing APT integration

This approach provides:

• ✅ Best tool for each job
• ✅ Proven, maintained tools
• ✅ Consistent user experience
• ✅ Manageable complexity
• ✅ Clear separation of concerns

Technical Hurdles and Challenges

Understanding the Installation Flow

How Anaconda Integrates with Bootc

The Fedora anaconda approach provides a clear model for understanding the technical challenges:

1. Anaconda ISO Creation: OSBuild generates an anaconda ISO with embedded kickstart configuration
2. Kickstart Integration: The ostreecontainer --url <container-image> directive tells anaconda to install the bootc container
3. Installation Process: Anaconda downloads the container and calls bootc install internally
4. System Configuration: The installed system boots into the OSTree-based bootc environment

Key Technical Challenge: Preseed vs Kickstart

• Fedora: Uses kickstart with ostreecontainer directive
• Debian: Uses preseed configuration system
• Challenge: No equivalent ostreecontainer directive exists in debian-installer preseed

Major Technical Hurdles

1. Preseed Integration Challenge

Problem: Debian-installer uses preseed, not kickstart

• Preseed limitations: No built-in support for container installation
• Custom integration needed: Must create custom preseed hooks or scripts
• Complexity: Requires deep understanding of debian-installer internals

Potential Solutions:

• Custom preseed script: Create preseed hook that downloads and installs bootc container
• Modified debian-installer: Extend debian-installer with bootc support
• Post-installation script: Install bootc after base system installation

2. Bootc Installation Integration

Problem: How to integrate bootc install into debian-installer workflow

• Timing: When during installation should bootc install run?
• Dependencies: bootc must be available in the installer environment
• Partitioning: Must align with debian-installer's partitioning scheme

Technical Requirements:

• bootc package: Must be available in installer environment (udeb)
• Container download: Network access during installation
• Installation order: Partition → Format → bootc install → Configure bootloader

3. Package Management Complexity

Problem: Different package systems between installer and target

• Installer packages: udebs (debian-installer packages)
• Target packages: Regular .deb packages
• bootc package: Must be available as both udeb and .deb

Challenges:

• Package availability: bootc may not be available as udeb
• Dependency resolution: Different dependency trees for installer vs target
• Repository management: Different repositories for installer vs target

4. Bootloader Configuration

Problem: Bootloader setup for bootc systems

• GRUB configuration: Must support OSTree-based booting
• Kernel parameters: Special parameters for bootc/OSTree systems
• UEFI/BIOS support: Different bootloader requirements

Technical Details:

• OSTree integration: GRUB must understand OSTree deployments
• Kernel selection: Must boot correct kernel from OSTree deployment
• Initramfs: May need custom initramfs for bootc systems

5. Network and Container Access

Problem: Container registry access during installation

• Network configuration: Must have network access during installation
• Registry authentication: May need credentials for private registries
• Container download: Large container images during installation

Challenges:

• Offline installation: How to handle offline scenarios?
• Bandwidth: Large container downloads during installation
• Authentication: Registry credentials management

Implementation Complexity Analysis

Simple-cdd Integration Challenges

Advantages:

• ✅ Proven tool: Well-maintained and documented
• ✅ Configuration-driven: Fits existing config system
• ✅ Debian-native: Designed for Debian systems

Challenges:

• ❌ Learning curve: Complex configuration system
• ❌ bootc integration: No built-in bootc support
• ❌ Customization needed: Significant modification required

OSBuild Extension Challenges

Advantages:

• ✅ Consistent approach: Same tool for disk images and installers
• ✅ Existing integration: Already integrated with project

Challenges:

• ❌ No debian-installer support: OSBuild doesn't support debian-installer
• ❌ Major development: Would require significant OSBuild modifications
• ❌ Maintenance burden: Ongoing OSBuild integration work

Direct debian-installer Modification

Advantages:

• ✅ Native integration: Built into debian-installer
• ✅ Clean approach: No external tool dependencies

Challenges:

• ❌ Complex development: Requires deep debian-installer knowledge
• ❌ Upstream integration: Changes need to be accepted upstream
• ❌ Maintenance: Ongoing debian-installer integration

Risk Assessment

High Risk Factors

1. Preseed limitations: No proven way to integrate bootc installation
2. Package availability: bootc may not be available as udeb
3. Bootloader complexity: OSTree bootloader configuration is complex
4. Network dependencies: Container download during installation

Medium Risk Factors

1. simple-cdd learning curve: Complex configuration system
2. Testing complexity: Difficult to test installer integration
3. Documentation gaps: Limited documentation for custom installer creation

Low Risk Factors

1. Existing APT integration: Can leverage existing package resolution
2. Configuration system: Existing config system can be extended
3. Container workflow: Existing container handling can be reused

Recommended Approach: Phased Implementation

Phase 1: Research and Prototype

1. Investigate preseed hooks: Research custom preseed script capabilities
2. Test bootc availability: Check if bootc is available as udeb
3. Prototype simple-cdd: Create basic simple-cdd configuration
4. Test container download: Verify network access during installation

Phase 2: Basic Integration

1. Create preseed script: Develop custom preseed hook for bootc installation
2. Integrate with simple-cdd: Add bootc support to simple-cdd configuration
3. Test basic workflow: Verify end-to-end installation process

Phase 3: Production Ready

1. Error handling: Add comprehensive error handling and recovery
2. Documentation: Create user documentation and examples
3. Testing: Comprehensive testing across different scenarios

Alternative: Focus on Disk Images Only

Given the technical complexity, consider removing installer support entirely:

Advantages:

• ✅ Simplified project: Focus on core disk image functionality
• ✅ Reduced complexity: No installer integration challenges
• ✅ Faster development: Can focus on disk image improvements
• ✅ Clear scope: Well-defined project boundaries

Disadvantages:

• ❌ Limited use cases: No installer-based deployment
• ❌ User expectations: Users may expect installer support
• ❌ Feature parity: Less feature-complete than Fedora version

Next Steps

1. Research preseed hooks and custom script capabilities
2. Investigate bootc udeb availability in Debian repositories
3. Prototype simple-cdd integration with basic bootc support
4. Test container download during installation process
5. Evaluate complexity vs. benefit of installer support
6. Consider focusing on disk images only if complexity is too high