Debian bootc-image-builder

A fork of the original bootc-image-builder adapted to support Debian-based container images, enabling the creation of Particle OS - an immutable, Debian-based atomic desktop system.

Project Overview

This project is fundamentally an osbuild module development project, not a simple bootc-image-builder fork. The bootc-image-builder tool is merely a thin Go wrapper that orchestrates osbuild manifests. The real work involves creating new osbuild stages that can handle Debian's mutable toolchain within an immutable paradigm.

Critical Insight

We're not just porting from Fedora to Debian; we're adapting a mutable toolchain (apt/dpkg, initramfs-tools) to work within an immutable system architecture (OSTree). This is a paradigm shift, not a simple translation.

Source Code Structure

debian-bootc-image-builder/
├── bib/                          # Main Go application (from original)
│   ├── cmd/                      # Command-line interfaces
│   ├── internal/                 # Internal packages
│   │   ├── aptsolver/           # APT package solver
│   │   ├── debian-patch/        # Debian-specific patches
│   │   ├── solver/              # Generic solver interface
│   │   ├── distrodef/           # Distribution definitions
│   │   └── imagetypes/          # Image type handling
│   └── data/                    # Distribution definitions
│       └── defs/                # YAML definition files
├── osbuild-stages/               # Debian-specific osbuild stages
│   ├── apt-stage/               # Debian package management
│   ├── debian-kernel-stage/     # Debian kernel handling
│   ├── debian-grub-stage/       # Debian GRUB configuration
│   └── debian-filesystem-stage/ # Debian filesystem setup
├── tests/                       # Test suite
│   ├── unit/                    # Unit tests for osbuild stages
│   ├── integration/             # Integration tests
│   └── performance/             # Performance tests
├── scripts/                     # Build and development scripts
├── containerfiles/              # Example container definitions
├── calamares/                   # Installer integration
└── customization/               # Customization examples

Development Setup

Prerequisites

• Go: >= 1.20
• Python: >= 3.8 (for osbuild development)
• Podman: Container runtime
• Git: Version control

Quick Start

# Clone the repository
git clone https://github.com/your-org/debian-bootc-image-builder.git
cd debian-bootc-image-builder

# Set up development environment
make setup-dev

# Build the project
make build

# Run tests
make test

Key Components

osbuild Stages

• apt-stage: Debian package management using APT/dpkg
• debian-kernel-stage: Kernel handling with initramfs-tools
• debian-grub-stage: GRUB configuration for Debian
• debian-filesystem-stage: Filesystem setup for immutable Debian

Go Integration

• bootc_validation.go: Debian bootc image validation
• aptsolver/: APT package solver implementation
• debian-patch/: Debian-specific patches and extensions

Distribution Definitions

• debian-13.yaml: Complete Debian Trixie distribution definition
• Multiple image types: qcow2, desktop, server
• Proper stage dependencies and execution order

Testing

# Run unit tests
make test-unit

# Run integration tests
make test-integration

# Run performance tests
make test-performance

# Run all tests
make test

Building

# Build the binary
make build

# Build container image
make build-container

# Build all components
make all

Contributing

This project follows the roadmap outlined in the main documentation. Please review the current phase and contribute accordingly.

Development Workflow

1. Check the current phase in the main documentation
2. Review the tasks and deliverables for that phase
3. Create feature branches for specific tasks
4. Write tests for new osbuild stages
5. Submit pull requests with comprehensive testing

Documentation

For comprehensive documentation, see:

• Documentation Index - Complete documentation overview
• Advanced Usage Guide - Complete Debian adaptation guide
• Project Status - Current development status
• Implementation Summary - Technical implementation details

License

This project is licensed under the same terms as the original bootc-image-builder project.

Acknowledgments

• Original bootc-image-builder team for the foundational work
• osbuild community for the excellent build system
• Debian community for the robust package management system