# 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