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

   sudo apt update
   sudo apt install debos
   

2. Go Dependencies: Ensure the project compiles

   go mod tidy
   go build ./internal/debos/...
   

Verification

Test that debos is working:

debos --help

Usage

Basic Image Building

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

// 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

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

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

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

// 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:

go test ./internal/debos/ -v

Integration Tests

Test with real debos (requires proper environment):

# 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

   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:

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
• debos User Guide
• OSTree Documentation

Examples

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

Community

• Debian OSTree Discussion
• debos Community
• OSTree Community

---

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