deb-bootc-image-builder/docs/particle-os_process.md

particle-os Process Guide

Overview

This guide covers the process of using particle-os to create bootable Debian-based operating system images. particle-os is a modified version of bootc-image-builder that includes disk creation capabilities, adapted from the original Fedora tooling to work with Debian systems.

Debian Atomic Foundation

particle-os builds on Debian Atomic, which provides the immutable OS foundation. Debian Atomic creates container images with:

• OSTree tools and structure
• Unified /usr hierarchy
• UEFI boot support
• Pure Debian 13+ (Trixie) base

particle-os uses these Debian Atomic container images as base images for creating bootable disk images. The workflow is:

1. Debian Atomic creates immutable container images
2. particle-os converts those containers to bootable disk images
3. Result: Bootable Debian-based immutable operating system

Current Status

particle-os is a working prototype with core functionality operational but incomplete.

What Works

• Container extraction and rootfs creation
• Package installation via apt in chroot
• Basic disk image creation with GPT partitioning
• Bootloader installation (extlinux/syslinux)
• YAML recipe parsing and validation
• Multiple output formats (raw, qcow2, vmdk, vdi)

What's Incomplete

• Some recipe stages fail due to chroot permission issues
• Kernel installation not fully implemented
• Limited error handling and recovery
• Images boot to bootloader but lack full OS boot capability

Prerequisites

System Requirements

• Debian 12+ (Bookworm/Trixie) or Ubuntu 22.04+
• Go 1.21+ for building from source
• sudo access for chroot operations
• 10GB+ free disk space
• 4GB+ RAM recommended

Dependencies

sudo apt update
sudo apt install golang-go qemu-utils podman

Installation

Build from Source

cd deb-bootc-image-builder
cd bib
go build -o particle-os cmd/particle_os/main.go
cd ..

Verify Installation

./bib/particle-os --version
./bib/particle-os --help

Basic Usage

List Available Recipes

./bib/particle-os list

Validate a Recipe

./bib/particle-os validate recipes/simple-cli-bootable.yml

Build an Image

sudo ./bib/particle-os build recipes/simple-cli-bootable.yml

Recipe System

Recipe Structure

Recipes are YAML files that define the build process:

name: simple-cli-bootable
description: Generate bootable image from simple-cli container
base-image: git.raines.xyz/robojerk/simple-cli:latest
image-version: "1.0"

stages:
  - type: org.osbuild.debian.apt
    options:
      packages: [systemd, ostree, linux-image-amd64]
  
  - type: org.osbuild.debian.locale
    options:
      locale: en_US.UTF-8
  
  - type: org.osbuild.qemu
    options:
      formats: ["raw", "qcow2"]
      size: "10G"
      filename: "simple-cli-bootable"

Available Stages

• org.osbuild.debian.apt: Package installation and management
• org.osbuild.debian.locale: Locale configuration
• org.osbuild.debian.timezone: Timezone configuration
• org.osbuild.debian.users: User creation and management
• org.osbuild.qemu: Image creation and formatting

Build Process

1. Container Extraction

• Downloads specified base container image
• Extracts filesystem to temporary directory
• Prepares chroot environment

2. Stage Execution

• Runs each stage in sequence
• Installs packages, configures system
• May fail on certain stages due to permission issues

3. Image Creation

• Creates disk image with GPT partitioning
• Installs bootloader (extlinux/syslinux)
• Generates output in specified formats

4. Output

• Raw disk image (.img)
• QCOW2 format for QEMU/KVM
• VMDK format for VMware
• VDI format for VirtualBox

Current Limitations

Stage Failures

Some stages may fail due to chroot permission issues:

• Locale generation
• Timezone configuration
• User creation

Bootability Issues

• Images boot to bootloader successfully
• Full OS boot requires kernel installation
• Init system setup incomplete

Error Handling

• Limited error recovery
• Error messages may be truncated
• Silent failures possible

Troubleshooting

Common Issues

Permission Denied Errors

# Ensure running with sudo
sudo ./bib/particle-os build recipe.yml

Stage Failures

• Check recipe validation first
• Verify base image exists and is accessible
• Review error logs for specific failure points

Build Failures

• Ensure sufficient disk space
• Check network connectivity for container downloads
• Verify all dependencies installed

Debug Mode

./bib/particle-os build -v recipe.yml

Testing Created Images

QEMU Testing

# Test raw image
qemu-system-x86_64 -hda output.img

# Test QCOW2 image
qemu-system-x86_64 -hda output.qcow2

Expected Behavior

• Image should be recognized as bootable
• System should boot to bootloader
• Full OS boot may not work due to missing kernel

Development Status

Working Components

• Container extraction: 95% complete
• Package management: 90% complete
• Recipe parsing: 100% complete
• Stage execution: 40% complete
• Image creation: 80% complete
• Bootloader installation: 85% complete

Next Steps

1. Fix remaining stage execution issues
2. Complete image creation pipeline
3. Implement kernel installation
4. Improve error handling and testing

Production Readiness

particle-os is NOT ready for production use.

Current limitations include:

• Incomplete stage execution
• Limited error handling
• Bootability issues
• Insufficient testing coverage

Alternative Approaches

If particle-os cannot complete the build process:

Manual Image Creation

• Use container extraction manually
• Create filesystem manually
• Install bootloader manually
• Test bootability manually

Container-Based Testing

• Test functionality within containers
• Validate concepts without full boot
• Use for development and testing

Conclusion

particle-os provides a foundation for creating bootable Debian images from containers, but requires completion of several components before it can reliably produce fully bootable systems. The tool demonstrates the concept and has working core functionality, but is not yet suitable for production use.

For development and testing purposes, particle-os can create images that boot to bootloader, allowing validation of the basic boot process. Full OS functionality requires addressing the remaining stage execution issues and implementing kernel installation.