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