320 lines
10 KiB
Markdown
320 lines
10 KiB
Markdown
# 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.
|