deb-bootc-image-builder-new/development-plan.md

Debian bootc-image-builder Development Plan

Project Overview

Create a Debian equivalent of the Fedora bootc-image-builder that can build bootable disk images from Debian bootc containers. The tool will adapt the existing architecture to work with the APT/DEB package management system while maintaining compatibility with the same output formats and functionality.

Goals

1. Primary Goal: Create a functional Debian bootc-image-builder for Debian 13 (Trixie)
2. Secondary Goal: Implement flexible configuration system to avoid hardcoded values
3. Tertiary Goal: Maintain compatibility with existing bootc ecosystem
4. Focus: Initially target only Debian 13 (Trixie) for development and testing

Architecture Adaptation

Core Components to Adapt

1. Package Management System

   • Replace DNF/RPM with APT/DEB
   • Adapt package resolution logic
   • Update repository handling

2. Distribution Definitions

   • Create Debian-specific package lists for Trixie
   • Adapt YAML structure for Debian packages
   • Focus on Debian 13 (Trixie) initially

3. Container Base Images

   • Replace Fedora base with Debian Trixie
   • Update package installation commands (dnf -> apt)
   • Adapt container build process
   • Use debian-forge packages (bootc, apt-ostree, osbuild)

4. Configuration System

   • Implement flexible registry configuration
   • Create version mapping system
   • Add container naming templates

Implementation Phases

Phase 1: Foundation Setup

Duration: 1-2 weeks Priority: High

1. Project Structure Setup

   • Create bib/cmd/debian-bootc-image-builder/ directory
   • Set up Go module with Debian-specific dependencies
   • Create basic project structure

2. Configuration System Implementation

   • Implement .config/registry.yaml configuration system
   • Create configuration loading and validation
   • Add support for multiple registry environments

3. Basic CLI Framework

   • Adapt main.go for Debian-specific naming
   • Update help text and documentation
   • Implement basic command structure

Phase 2: Package Management Integration

Duration: 2-3 weeks Priority: High

1. APT Integration

   • Replace DNF solver with APT-based solution
   • Implement package dependency resolution
   • Create APT repository handling

2. Package Cache Management

   • Adapt /rpmmd volume to /aptcache or similar
   • Implement APT package caching
   • Handle package metadata storage

3. Repository Configuration

   • Support Debian repositories (main, contrib, non-free)
   • Add support for custom repositories
   • Implement repository priority handling

Phase 3: Distribution Definitions

Duration: 1-2 weeks Priority: High

1. Debian Package Lists

   • Create debian-stable.yaml (Trixie)
   • Create debian-testing.yaml (Forky)
   • Create debian-unstable.yaml (Sid)
   • Define package sets for different image types

2. Package Definition Structure

   • Adapt YAML structure for Debian packages
   • Support different package categories
   • Handle package version specifications

Phase 4: Image Building Logic

Duration: 2-3 weeks Priority: High

1. Manifest Generation

   • Adapt image.go for Debian-specific logic
   • Update partition table handling
   • Implement Debian-specific boot configuration

2. Filesystem Support

   • Support ext4, xfs, btrfs filesystems
   • Implement Debian-specific filesystem options
   • Handle boot partition configuration

3. Kernel and Boot Configuration

   • Adapt kernel options for Debian
   • Implement GRUB configuration
   • Handle UEFI/BIOS boot modes

Phase 5: Container Build System

Duration: 1-2 weeks Priority: Medium

1. Containerfile Adaptation

   • Replace Fedora base with Debian
   • Update package installation commands
   • Adapt build process for Debian

2. Runtime Dependencies

   • Identify required Debian packages
   • Update package installation lists
   • Test container build process

Phase 6: Testing and Validation

Duration: 2-3 weeks Priority: High

1. Unit Testing

   • Adapt existing Go tests
   • Create Debian-specific test cases
   • Test package resolution logic

2. Integration Testing

   • Test with real Debian bootc containers
   • Validate output image formats
   • Test different Debian versions

3. End-to-End Testing

   • Build and boot test images
   • Validate system functionality
   • Performance testing

Phase 7: Documentation and Polish

Duration: 1-2 weeks Priority: Medium

1. Documentation

   • Update README for Debian
   • Create usage examples
   • Document configuration options

2. Error Handling

   • Improve error messages
   • Add helpful troubleshooting info
   • Validate input parameters

Debian-Forge Package Integration

The project will use packages from the debian-forge repository:

Key Packages

1. bootc: Bootable container runtime (equivalent to Fedora's bootc)
2. apt-ostree: APT-based ostree implementation (equivalent to rpm-ostree)
3. osbuild: Image building tool (same name as Fedora version)

Package Sources

• Repository: https://packages.debian-forge.org
• Components: main
• Priority: 400 (lower than main Debian repos)
• Architecture: Available for amd64, arm64, and other architectures

Integration Strategy

• Use debian-forge as primary source for bootc-related packages
• Fall back to main Debian repositories for standard packages
• Handle package dependencies and conflicts appropriately

Technical Challenges and Solutions

Challenge 1: Package Management Differences

Problem: DNF and APT have different APIs and behaviors Solution:

• Create APT wrapper similar to dnfjson.Solver
• Implement package resolution using APT libraries
• Handle package metadata differently
• Integrate debian-forge repository for bootc packages

Challenge 2: Repository Management

Problem: Debian repositories have different structure than Fedora Solution:

• Implement Debian repository handling
• Support multiple repository types
• Handle repository priorities and pinning

Challenge 3: Distribution Versioning

Problem: Debian uses codenames (stable, testing, unstable) vs numeric versions Solution:

• Implement codename to version mapping
• Focus on Debian 13 (Trixie) initially
• Support both codename and numeric version inputs
• Handle version transitions (e.g., stable updates)

Challenge 4: Boot Configuration

Problem: Debian may have different boot requirements Solution:

• Research Debian boot requirements
• Adapt kernel options and boot configuration
• Test with different hardware configurations

Configuration System Design

Registry Configuration (.config/registry.yaml)

registries:
  development:
    base_url: "git.raines.xyz"
    namespace: "debian"
    auth_required: true
    
  production:
    base_url: "docker.io"
    namespace: "debian"
    auth_required: false

active_registry: "development"

containers:
  bootc_base: "{registry}/{namespace}/debian-bootc:{version}"
  bootc_builder: "{registry}/{namespace}/bootc-image-builder:{tag}"
  
versions:
  debian:
    stable: "trixie"
    testing: "forky" 
    unstable: "sid"

Benefits of Flexible Configuration

1. Rapid Development: Easy to switch between development and production
2. Version Management: Centralized version mapping
3. Registry Flexibility: Support multiple container registries
4. Environment Adaptation: Easy deployment in different environments

File Structure Plan

bib/
├── cmd/
│   └── debian-bootc-image-builder/     # Main Debian application
│       ├── main.go                     # Adapted main.go
│       ├── image.go                    # Debian-specific image logic
│       ├── apt.go                      # APT integration
│       ├── config.go                   # Configuration management
│       └── [other adapted files]
├── data/
│   └── defs/
│       ├── debian-stable.yaml          # Trixie packages
│       ├── debian-testing.yaml         # Forky packages
│       └── debian-unstable.yaml        # Sid packages
├── internal/
│   ├── distrodef/                      # Adapted distro definitions
│   ├── imagetypes/                     # Image type management
│   └── config/                         # Configuration system
└── .config/
    └── registry.yaml                   # Registry configuration

Success Criteria

1. Functional Requirements

   • Build bootable images from Debian bootc containers
   • Support all output formats (qcow2, ami, vmdk, etc.)
   • Handle multiple Debian versions
   • Provide flexible configuration

2. Quality Requirements

   • Comprehensive test coverage
   • Clear documentation
   • Good error handling
   • Performance comparable to Fedora version

3. Compatibility Requirements

   • Compatible with existing bootc ecosystem
   • Support same CLI interface
   • Maintain configuration file compatibility

Risk Mitigation

1. Technical Risks

   • Risk: APT integration complexity
   • Mitigation: Start with simple APT wrapper, iterate

2. Compatibility Risks

   • Risk: Breaking changes in Debian
   • Mitigation: Test with multiple Debian versions

3. Performance Risks

   • Risk: Slower than Fedora version
   • Mitigation: Profile and optimize critical paths

Timeline Summary

• Phase 1-2: Foundation and Package Management (3-5 weeks)
• Phase 3-4: Distribution and Image Building (3-5 weeks)
• Phase 5-6: Container and Testing (3-5 weeks)
• Phase 7: Documentation and Polish (1-2 weeks)

Total Estimated Duration: 10-17 weeks

Next Steps

1. Set up development environment
2. Create basic project structure
3. Implement configuration system
4. Begin APT integration work
5. Create initial Debian package definitions

This plan provides a structured approach to creating a Debian bootc-image-builder while maintaining the flexibility and functionality of the original Fedora version.