first commit

2025-09-05 07:10:12 -07:00 · 2025-09-05 07:10:12 -07:00 · 7584207f76
commit 7584207f76
72 changed files with 12801 additions and 0 deletions
--- a/development-plan.md
+++ b/development-plan.md
@ -0,0 +1,320 @@
+# 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.