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

Check the current phase in the main documentation
Review the tasks and deliverables for that phase
Create feature branches for specific tasks
Write tests for new osbuild stages
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

4.8 KiB Raw Blame History