deb-bootc-image-builder/docs/debos-integration.md

# Debian Bootc Image Builder - debos Integration

## Overview

This module provides a complete debos-based backend for the Debian bootc-image-builder, replacing the complex osbuild integration with a simpler, Debian-native approach. Based on the insights from `debian-ostree-stuff.md`, this integration leverages debos's built-in OSTree support and Debian package management.

## Architecture

### Core Components

1. **DebosRunner** (`debos.go`)
   - Executes debos commands
   - Manages temporary files and directories
   - Handles command output and error reporting

2. **DebosBuilder** (`builder.go`)
   - High-level image building interface
   - Supports multiple image types (qcow2, raw, AMI)
   - Handles custom packages and actions

3. **OSTreeBuilder** (`ostree.go`)
   - Extends DebosBuilder with OSTree capabilities
   - Creates bootc-compatible OSTree images
   - Manages OSTree repository configuration

### Key Features

- **Native Debian Support**: Uses debos, a Debian-native image building tool
- **OSTree Integration**: Built-in support for immutable system images
- **Multiple Image Types**: qcow2, raw, AMI support
- **Custom Package Management**: Add custom packages during build
- **Template System**: Flexible YAML-based configuration
- **Architecture Support**: amd64, arm64, armhf, i386

## Installation

### Prerequisites

1. **debos**: Install the debos package
   ```bash
   sudo apt update
   sudo apt install debos
   ```

2. **Go Dependencies**: Ensure the project compiles
   ```bash
   go mod tidy
   go build ./internal/debos/...
   ```

### Verification

Test that debos is working:
```bash
debos --help
```

## Usage

### Basic Image Building

```go
import "github.com/particle-os/debian-bootc-image-builder/bib/internal/debos"

// Create builder
builder, err := debos.NewDebosBuilder("/tmp/work", "/tmp/output")
if err != nil {
    log.Fatal(err)
}

// Build options
options := &debos.BuildOptions{
    Architecture:   arch.Current(),
    Suite:          "trixie",
    ContainerImage: "debian:trixie",
    ImageTypes:     []string{"qcow2"},
    CustomPackages: []string{"vim", "htop"},
}

// Build image
result, err := builder.Build(options)
if err != nil {
    log.Fatal(err)
}

fmt.Printf("Build completed: %s\n", result.OutputPath)
```

### OSTree Image Building

```go
// Create OSTree builder
ostreeBuilder, err := debos.NewOSTreeBuilder("/tmp/work", "/tmp/output")
if err != nil {
    log.Fatal(err)
}

// Build bootc-compatible OSTree image
result, err := ostreeBuilder.BuildBootcOSTree(options)
if err != nil {
    log.Fatal(err)
}

fmt.Printf("OSTree image created: %s\n", result.OutputPath)
```

### Custom OSTree Configuration

```go
customConfig := debos.OSTreeConfig{
    Repository: "/custom/repo",
    Branch:     "custom/debian/trixie/amd64",
    Subject:    "Custom build",
    Body:       "Custom configuration",
    Mode:       "bare-user",
}

result, err := ostreeBuilder.BuildOSTree(options, customConfig)
```

## Template System

### Basic Template

```yaml
architecture: amd64
suite: trixie

actions:
  - action: debootstrap
    suite: trixie
    components: [main, contrib, non-free]
    mirror: http://deb.debian.org/debian

  - action: run
    description: Install packages
    script: |
      #!/bin/bash
      set -e
      apt-get update
      apt-get install -y systemd bash

  - action: image-partition
    imagename: debian-basic
    imagesize: 4G
    partitiontype: gpt
    mountpoints:
      - mountpoint: /
        size: 3G
        filesystem: ext4
      - mountpoint: /boot
        size: 1G
        filesystem: vfat
```

### OSTree Template

```yaml
architecture: amd64
suite: trixie

actions:
  - action: debootstrap
    suite: trixie
    components: [main, contrib, non-free]
    mirror: http://deb.debian.org/debian

  - action: run
    description: Install OSTree packages
    script: |
      #!/bin/bash
      set -e
      apt-get update
      apt-get install -y ostree ostree-boot dracut

  - action: ostree-commit
    repository: /ostree/repo
    branch: debian/trixie/amd64
    subject: "Initial commit"
    body: "Base system with OSTree"

  - action: image-partition
    imagename: debian-ostree
    imagesize: 8G
    partitiontype: gpt
    mountpoints:
      - mountpoint: /
        size: 6G
        filesystem: ext4
      - mountpoint: /ostree
        size: 2G
        filesystem: ext4
```

## Integration with bootc-image-builder

### CLI Integration

The debos backend can be integrated into the existing bootc-image-builder CLI by:

1. **Replacing osbuild calls** with debos execution
2. **Maintaining CLI compatibility** for existing users
3. **Adding debos-specific options** for advanced users

### Example Integration

```go
// In cmdBuild function
if useDebosBackend {
    // Use debos instead of osbuild
    builder, err := debos.NewOSTreeBuilder(workDir, outputDir)
    if err != nil {
        return fmt.Errorf("failed to create debos builder: %w", err)
    }
    
    result, err := builder.BuildBootcOSTree(buildOptions)
    if err != nil {
        return fmt.Errorf("debos build failed: %w", err)
    }
    
    // Handle result
    fmt.Printf("Image built: %s\n", result.OutputPath)
} else {
    // Use existing osbuild path
    // ... existing code ...
}
```

## Testing

### Unit Tests

Run the test suite:
```bash
go test ./internal/debos/ -v
```

### Integration Tests

Test with real debos (requires proper environment):
```bash
# Test basic template
debos --dry-run debos-templates/debian-bootc-basic.yaml

# Test OSTree template
debos --dry-run debos-templates/debian-bootc-ostree.yaml
```

### Demo Programs

- `debos-demo.go`: Basic debos integration demo
- `debos-ostree-demo.go`: OSTree integration demo

## Best Practices

### Template Design

1. **Start Simple**: Begin with basic debootstrap + essential packages
2. **Add OSTree**: Integrate OSTree after basic system works
3. **Customize**: Add custom packages and configurations
4. **Test Incrementally**: Test each action before adding the next

### OSTree Configuration

1. **Repository Structure**: Use consistent branch naming (`debian/suite/arch`)
2. **Mode Selection**: Use `bare-user` for most cases
3. **Boot Integration**: Ensure proper GRUB and dracut configuration
4. **Partition Layout**: Dedicate space for OSTree repository

### Error Handling

1. **Check debos Output**: Always examine build logs
2. **Validate Templates**: Test templates in dry-run mode first
3. **Handle Failures**: Implement proper error reporting and recovery

## Troubleshooting

### Common Issues

1. **debos Not Found**
   ```bash
   sudo apt install debos
   ```

2. **Permission Errors**
   - Ensure proper directory permissions
   - Check if running in container with proper mounts

3. **Template Errors**
   - Validate YAML syntax
   - Check action names and parameters
   - Use `--dry-run` to debug

4. **Build Failures**
   - Check debos output for specific errors
   - Verify package availability in repositories
   - Ensure sufficient disk space

### Debug Mode

Use debos debug options:
```bash
debos --debug-shell --verbose template.yaml
```

## Performance Considerations

### Build Times

- **Basic System**: 5-15 minutes
- **OSTree Integration**: 10-25 minutes
- **Custom Packages**: +2-5 minutes per package

### Resource Requirements

- **Memory**: 2-4GB minimum
- **Disk Space**: 2x image size for build process
- **CPU**: 2+ cores recommended

### Optimization Tips

1. **Use Caching**: Leverage debos caching mechanisms
2. **Parallel Actions**: Group independent actions
3. **Minimal Packages**: Only install essential packages
4. **Efficient Scripts**: Minimize shell script complexity

## Future Enhancements

### Planned Features

1. **Container Integration**: Direct container image processing
2. **Cloud Integration**: Enhanced cloud platform support
3. **Plugin System**: Extensible action system
4. **CI/CD Integration**: Automated build pipelines

### Community Contributions

1. **Template Library**: Share and reuse templates
2. **Action Development**: Create custom debos actions
3. **Documentation**: Improve guides and examples
4. **Testing**: Expand test coverage and scenarios

## Resources

### Documentation

- [debos GitHub](https://github.com/go-debos/debos)
- [debos User Guide](https://github.com/go-debos/debos/wiki)
- [OSTree Documentation](https://ostree.readthedocs.io/)

### Examples

- `debos-templates/`: Template examples
- `debos-demo.go`: Basic usage examples
- `debos-ostree-demo.go`: OSTree integration examples

### Community

- [Debian OSTree Discussion](debian-cloud@lists.debian.org)
- [debos Community](https://github.com/go-debos/debos/discussions)
- [OSTree Community](https://ostree.readthedocs.io/en/latest/community.html)

---

**Status**: Active Development  
**Version**: 1.0.0  
**Last Updated**: August 2025  
**Maintainer**: Debian Bootc Image Builder Team