deb-bootc-image-builder/docs/PARTICLE_OS_CONTAINER_COMPATIBILITY.md

particle-os Container Compatibility Analysis

Date: August 17, 2025
Status: Analysis and Planning Phase
Scope: Debian-native equivalent to bootc-image-builder for particle-os containers

---

🎯 Project Scope Clarification

What We're Building

• Input: particle-os containers (Debian-based, OSTree + bootc + bootupd)
• Process: Convert to bootable disk images
• Output: Bootable Debian OS images
• Architecture: Debian-native equivalent to bootc-image-builder

The Complete Workflow

1. particle-os creates Debian-based container images (similar to ublue-os)
2. deb-bootc-image-builder (our tool) processes those containers into bootable disk images
3. Result: Bootable Debian OS images that can be deployed to hardware

---

🔍 particle-os Ecosystem Analysis

Based on the provided context, here's what we understand about the particle-os ecosystem:

Core Components

Component	Repository	Status	Purpose
debian-atomic	git.raines.xyz/particle-os/debian-atomic	Similar to Fedora Atomic	Base atomic OS foundation
particle-os	git.raines.xyz/particle-os/particle-os	ublue-os equivalent for Debian	Custom OS image creation
apt-ostree	git.raines.xyz/particle-os/apt-ostree	Early development	Debian equivalent to rpm-ostree
bootc	git.raines.xyz/particle-os/bootc	Unchanged fork	Boot management with Debian packaging
deb-bootupd	git.raines.xyz/particle-os/deb-bootupd	Early development	Debian equivalent to bootupd

Key Insights

1. debian-atomic: Provides the atomic OS foundation (similar to Fedora Atomic)
2. particle-os: Creates custom OS images (equivalent to ublue-os)
3. apt-ostree: Package management for atomic updates (equivalent to rpm-ostree)
4. bootc: Boot management (unchanged from upstream, just Debian packaged)
5. deb-bootupd: Boot update management (equivalent to bootupd)

---

🏗️ Architecture Requirements

What We Need to Implement

1. OSTree Integration (apt-ostree)

• Repository Operations: Handle apt-ostree repositories
• Deployment Management: Manage OSTree deployments
• Boot Configuration: Configure OSTree boot settings
• Package Management: Integrate with apt-ostree for atomic updates

2. bootc Integration

• Configuration: Parse and apply bootc configuration
• Boot Management: Handle bootc boot processes
• Deployment: Integrate with bootc deployment workflows
• Compatibility: Ensure compatibility with Debian-packaged bootc

3. bootupd Integration (deb-bootupd)

• Update Management: Handle bootupd update processes
• Boot Configuration: Manage bootupd configuration
• Deployment: Integrate with bootupd deployment workflows
• Compatibility: Ensure compatibility with Debian-packaged bootupd

---

🔧 Implementation Strategy

Phase 1: OSTree Integration (apt-ostree)

Required Stages

- type: org.osbuild.debian.ostree
  options:
    repository_url: "https://git.raines.xyz/particle-os/debian-atomic"
    branch: "main"
    deployment_type: "atomic"
    package_manager: "apt-ostree"

- type: org.osbuild.debian.ostree_boot
  options:
    boot_config: "ostree"
    deployment_name: "particle-os-deployment"
    kernel_args: "ostree=/ostree/boot.1/debian-atomic/main/0"

Implementation Requirements

• apt-ostree Integration: Handle Debian-specific OSTree operations
• Repository Management: Clone and manage apt-ostree repositories
• Deployment Creation: Create OSTree deployments
• Boot Configuration: Configure bootloader for OSTree

Phase 2: bootc Integration

Required Stages

- type: org.osbuild.debian.bootc
  options:
    config_file: "/etc/bootc/config.yaml"
    deployment_type: "atomic"
    boot_method: "ostree"
    kernel_args: "bootc.ostree=/ostree/boot.1/debian-atomic/main/0"

Implementation Requirements

• Configuration Parsing: Parse bootc configuration files
• Boot Process: Integrate with bootc boot management
• Deployment: Handle bootc deployment workflows
• Compatibility: Ensure Debian packaging compatibility

Phase 3: bootupd Integration (deb-bootupd)

Required Stages

- type: org.osbuild.debian.bootupd
  options:
    config_file: "/etc/bootupd/config.yaml"
    update_method: "atomic"
    deployment_source: "ostree"
    auto_update: true

Implementation Requirements

• Configuration Management: Handle bootupd configuration
• Update Process: Integrate with bootupd update workflows
• Deployment: Manage bootupd deployment processes
• Compatibility: Ensure Debian packaging compatibility

---

📋 Stage Implementation Plan

New Stage Types to Implement

1. OSTree Stages

// org.osbuild.debian.ostree
type OSTreeStage struct {
    RepositoryURL string `yaml:"repository_url"`
    Branch        string `yaml:"branch"`
    DeploymentType string `yaml:"deployment_type"`
    PackageManager string `yaml:"package_manager"`
}

// org.osbuild.debian.ostree_boot
type OSTreeBootStage struct {
    BootConfig    string `yaml:"boot_config"`
    DeploymentName string `yaml:"deployment_name"`
    KernelArgs    string `yaml:"kernel_args"`
}

2. bootc Stages

// org.osbuild.debian.bootc
type BootcStage struct {
    ConfigFile    string `yaml:"config_file"`
    DeploymentType string `yaml:"deployment_type"`
    BootMethod    string `yaml:"boot_method"`
    KernelArgs    string `yaml:"kernel_args"`
}

3. bootupd Stages

// org.osbuild.debian.bootupd
type BootupdStage struct {
    ConfigFile    string `yaml:"config_file"`
    UpdateMethod  string `yaml:"update_method"`
    DeploymentSource string `yaml:"deployment_source"`
    AutoUpdate    bool   `yaml:"auto_update"`
}

---

🧪 Testing Requirements

Test Recipes Needed

1. Basic OSTree Recipe

name: "ostree-test"
description: "Test OSTree integration with debian-atomic"
base-image: "debian:trixie-slim"

stages:
  - type: org.osbuild.debian.ostree
    options:
      repository_url: "https://git.raines.xyz/particle-os/debian-atomic"
      branch: "main"
      deployment_type: "atomic"
      package_manager: "apt-ostree"

  - type: org.osbuild.debian.ostree_boot
    options:
      boot_config: "ostree"
      deployment_name: "test-deployment"
      kernel_args: "ostree=/ostree/boot.1/debian-atomic/main/0"

2. Complete particle-os Recipe

name: "particle-os-complete"
description: "Complete particle-os container processing"
base-image: "debian:trixie-slim"

stages:
  - type: org.osbuild.debian.ostree
    options:
      repository_url: "https://git.raines.xyz/particle-os/debian-atomic"
      branch: "main"
      deployment_type: "atomic"
      package_manager: "apt-ostree"

  - type: org.osbuild.debian.bootc
    options:
      config_file: "/etc/bootc/config.yaml"
      deployment_type: "atomic"
      boot_method: "ostree"
      kernel_args: "bootc.ostree=/ostree/boot.1/debian-atomic/main/0"

  - type: org.osbuild.debian.bootupd
    options:
      config_file: "/etc/bootupd/config.yaml"
      update_method: "atomic"
      deployment_source: "ostree"
      auto_update: true

  - type: org.osbuild.qemu
    options:
      formats: ["raw", "qcow2"]
      size: "10G"
      filename: "particle-os-complete"

---

🚨 Critical Dependencies

System Requirements

• apt-ostree: Debian equivalent to rpm-ostree
• bootc: Boot management tool
• deb-bootupd: Boot update management tool
• OSTree: Atomic update system

Development Dependencies

• Go 1.21+: For binary compilation
• Development Tools: For building and testing
• Documentation: For understanding particle-os ecosystem

---

📊 Implementation Timeline

Phase 4b: particle-os Container Compatibility (2-3 weeks)

Week	Focus	Deliverables
Week 1	OSTree Integration	Basic OSTree stages, repository operations
Week 2	bootc Integration	bootc stages, configuration management
Week 3	bootupd Integration	bootupd stages, update management

Success Criteria

• OSTree stages execute successfully
• bootc stages execute successfully
• bootupd stages execute successfully
• Complete particle-os container processing works
• Test recipes validate all functionality

---

🎯 Next Steps

Immediate Actions (When Go Available)

1. Recompile binary with current sudo fixes
2. Test basic stages to ensure foundation works
3. Begin OSTree integration implementation
4. Create test recipes for validation

Research Requirements

1. Study apt-ostree: Understand Debian OSTree implementation
2. Analyze bootc: Understand boot management requirements
3. Examine deb-bootupd: Understand update management requirements
4. Review debian-atomic: Understand base atomic OS structure

---

💡 Key Insights

What We've Learned

1. particle-os is the ublue-os equivalent for Debian systems
2. debian-atomic provides the foundation (similar to Fedora Atomic)
3. apt-ostree handles package management (equivalent to rpm-ostree)
4. bootc and deb-bootupd handle boot management (equivalent to upstream tools)

What This Means for Our Project

1. We need to implement OSTree integration for apt-ostree compatibility
2. We need to implement bootc integration for boot management
3. We need to implement bootupd integration for update management
4. We need to understand debian-atomic for base OS foundation

---

🏆 Conclusion

The particle-os ecosystem provides a complete Debian-native equivalent to the ublue-os ecosystem. Our deb-bootc-image-builder needs to implement:

1. OSTree integration for atomic updates and deployments
2. bootc integration for boot management
3. bootupd integration for update management
4. Complete container processing from particle-os containers to bootable images

This represents a significant implementation effort but will result in a production-ready tool that can process particle-os containers just like bootc-image-builder processes ublue-os containers.

---

Last Updated: August 17, 2025
Status: Analysis and Planning Complete
Next Phase: Implementation of OSTree, bootc, and bootupd Integration
Timeline: 2-3 weeks for particle-os container compatibility