deb-bootc-compose/README.md

deb-bootc-compose

Debian's equivalent to Fedora's Pungi compose system

deb-bootc-compose is a Debian-native composition tool that orchestrates the creation of Debian bootc images from packages. It coordinates the entire compose process, similar to how Pungi coordinates Fedora's release process.

What It Does

deb-bootc-compose serves as the main orchestrator for Debian's bootc ecosystem:

• Package Coordination: Ensures all release artifacts use identical package versions across variants
• Multi-Artifact Generation: Creates container images, disk images, and other bootc artifacts
• Build Orchestration: Coordinates with deb-orchestrator (Koji equivalent) and deb-mock (Mock equivalent)
• OSTree Integration: Orchestrates bootc image creation through apt-ostree
• Variant Management: Handles different Debian variants (minimal, server, desktop, etc.)

Architecture

The tool follows a phase-based architecture inspired by Pungi:

┌─────────────────┐    ┌─────────────────┐    ┌─────────────────┐
│ deb-bootc-      │    │ deb-orchestrator│    │    deb-mock     │
│   compose       │    │   (Koji equiv)  │    │   (Mock equiv)  │
│ Orchestrator    │    │ Build System    │    │Build Environment│
└─────────────────┘    └─────────────────┘    └─────────────────┘
         │                       │                       │
         │ Coordinates           │ Manages               │ Creates
         │ entire process        │ package building      │ isolated
         │                       │ at scale              │ environments

Core Phases

1. init: Initialize compose environment
2. gather: Download and organize packages
3. build: Build packages if needed
4. ostree: Create OSTree commits
5. output: Generate output artifacts
6. cleanup: Clean up temporary files

Quick Start

Prerequisites

• Go 1.21 or later
• Debian-based system (for development)
• Basic understanding of Debian packaging

Installation

# Clone the repository
git clone https://github.com/debian/deb-bootc-compose.git
cd deb-bootc-compose

# Install dependencies
make deps

# Build the binary
make build

# Run with help
./build/deb-bootc-compose --help

Basic Usage

# Run a compose with a treefile
./build/deb-bootc-compose \
    --treefile examples/debian-bootc-minimal.json \
    --output ./compose-output \
    --config configs/compose.yaml

Configuration

Compose Configuration

The main configuration file (compose.yaml) controls:

• Compose settings: Release, variants, architectures
• Build system: sbuild, debootstrap integration
• OSTree settings: Repository mode, signing
• Output formats: Container, disk image, chunked OCI
• Integration: deb-orchestrator connection settings

Treefiles

Treefiles (JSON manifests) define what gets built:

• Package lists: Required, optional, recommended packages
• Variants: Different flavors (minimal, server, desktop)
• Architectures: Target CPU architectures
• Repositories: Package sources
• Build settings: Build system configuration

Example treefile structure:

{
  "name": "debian-bootc-minimal",
  "version": "13",
  "release": "bookworm",
  "packages": {
    "required": ["linux-image-amd64", "systemd", "ostree", "bootc"]
  },
  "architecture": ["amd64", "arm64"],
  "variants": [
    {
      "name": "minimal",
      "description": "Minimal base system"
    }
  ]
}

Development

Project Structure

deb-bootc-compose/
├── cmd/                    # Command-line interfaces
│   ├── compose/           # Main compose command
│   └── cli/              # CLI utilities
├── internal/              # Internal packages
│   ├── compose/           # Core compose engine
│   ├── config/            # Configuration management
│   ├── ostree/            # OSTree integration
│   └── build/             # Build system interface
├── pkg/                   # Public packages
├── configs/               # Configuration files
├── examples/              # Example treefiles
└── docs/                  # Documentation

Building

# Build everything
make all

# Build specific components
make build      # Main binary
make cli        # CLI tool

# Development helpers
make test       # Run tests
make fmt        # Format code
make lint       # Lint code
make clean      # Clean build artifacts

Testing

# Run all tests
make test

# Run tests with coverage
make test-coverage

# Run with sample treefile
make run-sample

Integration

With deb-orchestrator

deb-bootc-compose integrates with deb-orchestrator for:

• Package management: Downloading packages from build system
• Build coordination: Ensuring package availability before compose
• Metadata integration: Using build metadata for versioning

With deb-mock

deb-bootc-compose can use deb-mock for:

• Build environment creation: Isolated chroot environments
• Package installation: Installing build dependencies
• Environment isolation: Reproducible builds

Status

Current Status: Phase 1 - Foundation Development

• ✅ Core engine: Basic compose engine implemented
• ✅ Treefile parser: JSON-based configuration system
• ✅ Phase management: Simple phase execution system
• ✅ Configuration: YAML-based configuration system
• 🔄 OSTree integration: Placeholder implementation
• 🔄 Build system: Placeholder implementation
• ❌ Integration: Not yet integrated with other tools

Roadmap

See the main project TODO.md for the complete development roadmap.

Phase 1 (Months 1-6): Foundation

• Core compose engine working
• Basic treefile parsing and validation
• OSTree integration functional
• Container output working

Phase 2 (Months 7-10): Integration

• Deep integration with deb-orchestrator and deb-mock
• Advanced features and optimization
• Production readiness features

Phase 3 (Months 11-14): Production

• Security audit and hardening
• Performance optimization
• Community integration

Phase 4 (Months 15-18): Ecosystem

• Debian Atomic and Particle-OS variants
• Advanced use cases
• Community adoption

Contributing

We welcome contributions! Please see our Contributing Guide for details.

Development Setup

# Set up development environment
make dev-setup

# Install development tools
go install github.com/golangci/golangci-lint/cmd/golangci-lint@latest

License

This project is licensed under the same terms as Debian (GPL-2+).

Related Projects

• deb-orchestrator: Debian's equivalent to Fedora's Koji build system
• deb-mock: Debian's equivalent to Fedora's Mock build environment manager
• deb-bootc-compose: This project - the main orchestrator

Support

• Issues: GitHub Issues
• Discussions: GitHub Discussions
• Documentation: Project Wiki

---

Part of Debian's complete bootc ecosystem - building Debian's answer to Fedora's Pungi-Koji-Mock ecosystem.