first commit

docs/debian-installer.md

@@ -0,0 +1,300 @@
+# 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**:
+   ```bash
+   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