deb-bootc-image-builder/docs/HOW-TO-USE.md

How to Use deb-bootc-image-builder

🎯 Current Status: PARTIALLY WORKING PROTOTYPE ⚠️

⚠️ IMPORTANT: This tool is currently a working prototype with significant gaps. It demonstrates the concept and has working foundations, but critical limitations exist that prevent reliable production use.

---

📋 What's Actually Working

✅ Core Infrastructure (95% Complete)

• Container extraction: Successfully extracts Docker/Podman container images
• Package management: apt package installation works correctly in chroot
• Basic image creation: Creates GPT partition tables and ext4 filesystems
• Recipe system: YAML recipe parsing and validation functional
• CLI framework: Professional command-line interface with Cobra

✅ What You Can Do Right Now

• Extract containers and create rootfs
• Install packages using apt (apt stage works completely)
• Create basic disk image structure
• Parse and validate recipes
• Generate raw disk images with proper partitioning

---

🚨 What's NOT Working (Critical Gaps)

❌ Stage Execution Failures

• Locale stage: Fails during locale generation (chroot permission issues)
• Timezone stage: Untested, likely has similar permission issues
• Users stage: Untested, may have chroot permission problems
• OSTree stages: Just placeholders, no actual functionality
• Bootupd stage: Just placeholder, no actual configuration

❌ Image Creation Pipeline

• Final image creation: The createFinalImage() function exists but isn't reached due to stage failures
• Output formats: Only raw format is tested, qcow2/vmdk/vdi untested
• Bootability: Images lack kernels and proper boot configuration

❌ Production Readiness

• Error handling: Poor error recovery and truncated error messages
• Testing: No comprehensive validation or testing
• Bootability: Cannot reliably produce bootable images

---

🚀 Installation & Setup

Prerequisites

# Required tools
sudo apt install podman docker.io parted mkfs.ext4 extlinux

# Optional (for additional features)
sudo apt install qemu-utils fakemachine

Current Installation Status

• Binary: Pre-compiled binary available in bib/particle-os
• Source: Go source code available in bib/ directory
• Dependencies: All required tools must be installed manually

---

📖 Command-Line Usage

Basic Commands

Build an Image (Limited Functionality)

# Basic build (apt stage only works)
./bib/particle-os build recipes/minimal-debug.yml

# With verbose output
./bib/particle-os build recipes/minimal-debug.yml --verbose

# Specify work directory
./bib/particle-os build recipes/minimal-debug.yml --work-dir /tmp/custom-build

# Clean up after build
./bib/particle-os build recipes/minimal-debug.yml --clean

List Available Recipes

./bib/particle-os list

Validate a Recipe

./bib/particle-os validate recipes/minimal-debug.yml

Check Version

./bib/particle-os version

Container Operations

# List available containers
./bib/particle-os container list

# Inspect a container
./bib/particle-os container inspect debian:trixie-slim

Global Flags

--verbose, -v    # Enable verbose logging
--work-dir, -w   # Specify working directory for builds

Build Flags

--output, -o     # Output path for the image
--clean, -c      # Clean up work directory after build
--json, -j       # Output results in JSON format (CI/CD friendly)
--quiet, -q      # Suppress non-essential output (CI/CD friendly)

---

📝 Recipe Format

Basic Recipe Structure

name: my-custom-image
description: A custom Debian-based image
base-image: debian:trixie-slim
image-version: "1.0"

stages:
  - type: org.osbuild.debian.apt
    options:
      packages:
        - bash
        - coreutils
        - locales
      update: true
      clean: true

  - type: org.osbuild.debian.locale
    options:
      language: en_US.UTF-8
      default_locale: en_US.UTF-8

  - type: org.osbuild.debian.timezone
    options:
      timezone: UTC

  - type: org.osbuild.debian.users
    options:
      users:
        admin:
          password: "$6$rounds=656000$salt$hashed_password"
          shell: /bin/bash
          groups: ["sudo", "users"]
          uid: 1000
          gid: 1000
          home: /home/admin
          comment: "Administrator User"

  - type: org.osbuild.qemu
    options:
      formats: ["raw", "qcow2"]
      size: "5G"
      filename: "my-custom-image"

output:
  formats: ["raw", "qcow2"]
  size: "5G"
  path: "my-custom-image"

metadata:
  author: "Your Name"
  category: "custom"
  tags: ["custom", "debian", "particle-os"]

Available Stage Types

✅ Working Stages

• org.osbuild.debian.apt: Package installation (✅ WORKING)
• org.osbuild.debian.sources: Package source configuration (✅ WORKING)

❌ Broken/Incomplete Stages

• org.osbuild.debian.locale: Locale configuration (❌ FAILS DUE TO PERMISSIONS)
• org.osbuild.debian.timezone: Timezone configuration (❌ UNTESTED, LIKELY BROKEN)
• org.osbuild.debian.users: User creation (❌ UNTESTED, LIKELY BROKEN)

🔧 Placeholder Stages (Not Implemented)

• org.osbuild.debian.ostree: OSTree repository operations
• org.osbuild.debian.ostree_boot: OSTree boot configuration
• org.osbuild.ostree_deploy: OSTree deployment

🔧 Image Creation Stage

• org.osbuild.qemu: QEMU image creation (⚠️ FRAMEWORK EXISTS, NEVER REACHED)

---

🧪 Testing & Development

Current Test Recipes

• minimal-debug.yml: Basic apt stage testing (✅ WORKING)
• minimal-debug-locale.yml: Locale stage testing (❌ FAILS DUE TO PERMISSIONS)
• simple-cli-bootable.yml: Full workflow testing (❌ FAILS DUE TO STAGE ISSUES)

Testing Workflow

# 1. Test basic functionality (should work)
./bib/particle-os build recipes/minimal-debug.yml --verbose

# 2. Test with locale stage (currently fails)
./bib/particle-os build recipes/minimal-debug-locale.yml --verbose

# 3. Test full workflow (currently fails)
./bib/particle-os build recipes/simple-cli-bootable.yml --verbose

Debugging Tips

• Use --verbose flag for detailed logging
• Check work directory for intermediate files
• Monitor disk space (builds require significant space)
• Use --work-dir to specify custom working directory

---

🔧 Development & Compilation

Current Source Status

• Go source: Complete in bib/ directory
• Permission fixes: Some fixes implemented but not comprehensive
• Binary: Needs recompilation to include latest fixes

Compilation (When Go is Available)

cd bib
go build -o particle-os cmd/particle_os/main.go
cd ..

What's Fixed in Source

• ✅ Some permission fixes for chroot operations
• ✅ Basic error handling improvements
• ✅ Helper functions for file operations

---

🎯 Planned Features (Not Yet Implemented)

Phase 1: Complete Stage Execution (1-2 weeks)

• Fix remaining stage permission issues
• Test all stages complete successfully
• Validate end-to-end workflow

Phase 2: Complete Image Creation (2-3 weeks)

• Integrate working image creation into main build flow
• Test all output formats (raw, qcow2, vmdk, vdi)
• Add proper error handling and recovery

Phase 3: Improve Bootability (2-3 weeks)

• Add kernel installation capability
• Implement proper init system setup
• Test full OS boot process

Phase 4: Production Readiness (2-4 weeks)

• Add comprehensive testing
• Improve error handling
• Add disk space management
• Complete documentation

---

🚨 Known Issues & Limitations

Critical Issues

1. Stage failures: Locale, timezone, and users stages fail due to permission issues
2. Image creation: Final image creation never reached due to stage failures
3. Bootability: Generated images lack kernels and proper boot configuration
4. Error handling: Poor error recovery and truncated error messages

Environment Dependencies

1. sudo access: Required for chroot operations and file operations
2. Disk space: Builds require significant temporary storage
3. Tool availability: parted, mkfs.ext4, extlinux must be installed
4. Container tools: podman or docker required

Base Image Limitations

1. Only tested: debian:trixie-slim
2. Architecture: x86_64 only
3. Kernel support: Base images lack kernels
4. Boot system: Minimal boot configuration only

---

💡 Getting Help

Current Status Documentation

• current_stats.md: Realistic assessment of capabilities
• todo: Detailed project status and next steps
• DEVELOPMENT_ROADMAP.md: Strategic development plan

Reporting Issues

• Stage failures: Include verbose output and recipe used
• Permission issues: Check sudo access and tool availability
• Build failures: Verify disk space and tool installation

Development Progress

• Current phase: Critical issue resolution
• Timeline: 6-8 weeks to production readiness
• Focus: Fix stage execution failures first

---

🎉 What We've Achieved

Despite the limitations, we have:

1. ✅ Working prototype: Demonstrates container-to-image conversion concept
2. ✅ Solid foundation: Core infrastructure is functional and well-designed
3. ✅ Professional CLI: User-friendly command-line interface
4. ✅ Recipe system: Flexible YAML-based configuration
5. ✅ Container integration: Real Docker/Podman support

The tool shows great promise and has the right architecture for production use, but needs focused development to address the critical gaps.

---

Last Updated: August 17, 2025 20:00 Status: ⚠️ PARTIALLY WORKING PROTOTYPE - Development in Progress
Next Milestone: Fix Stage Execution Failures
Production Readiness: 20% (estimated 6-8 weeks to completion) Source: Based on current_stats.md - realistic assessment