particle-os/bootc.md

bootc in Particle OS: Complete Usage and Workflow Guide

bootc (bootable containers) is the central technology that powers Particle OS's approach to immutable desktop operating systems. This document provides a comprehensive overview of how bootc is used throughout the Particle OS ecosystem for building, distributing, and deploying atomic desktop systems based on Debian.

Overview: bootc's Role in Particle OS

Particle OS leverages bootc to transform the traditional Debian operating system model from package-based installations to container-based deployments. bootc enables the entire operating system—including the kernel, system libraries, desktop environment, and applications—to be packaged, versioned, and deployed as OCI container images.

Critical Debian-Specific Requirements

Essential Disk Utilities for bootc Deployment

⚠️ CRITICAL REQUIREMENT: Successful deployment using bootc install to-disk requires specific disk utilities that are often missing from minimal Debian environments.

Required Utilities:

• sfdisk (from util-linux) - CRITICAL for automated partitioning
• parted - Alternative partitioning tool
• mkfs.ext4 (from e2fsprogs) - Filesystem creation
• mkfs.fat (from dosfstools) - FAT32 filesystem for EFI
• grub-install - Bootloader installation
• efibootmgr - UEFI boot manager

Installation:

# Install required utilities in Debian
sudo apt update
sudo apt install -y util-linux parted e2fsprogs dosfstools grub-efi-amd64 efibootmgr

# Verify availability
which sfdisk parted mkfs.ext4 mkfs.fat grub-install efibootmgr

PATH Issues in Debian Environments

Common Problem: sfdisk exists but isn't found due to incomplete PATH in minimal Debian environments.

Diagnosis:

# Check if util-linux is installed
dpkg -l | grep util-linux

# Find sfdisk location
find / -name sfdisk 2>/dev/null

# Check current PATH
echo $PATH

# Test sfdisk directly
/usr/sbin/sfdisk --version

Solution - Use Explicit PATH:

# Fix PATH and run bootc
sudo env PATH="/usr/sbin:/sbin:/usr/local/bin:/usr/bin:/bin" \
  podman run --rm --privileged --pid=host --volume /dev:/dev \
  localhost/debian-atomic:latest /usr/bin/bootc install to-disk /dev/target-device

Container Environment Considerations

Containerfile Requirements:

FROM debian:trixie

# Install essential packages including disk utilities
RUN apt-get update && apt-get install -y \
    systemd \
    dbus \
    sudo \
    util-linux \  # CRITICAL: Provides sfdisk
    parted \
    e2fsprogs \   # CRITICAL: Provides mkfs.ext4
    dosfstools \  # CRITICAL: Provides mkfs.fat
    grub-efi-amd64 \
    efibootmgr \
    # ... other packages

# Ensure PATH includes system utilities directories
ENV PATH="/usr/sbin:/sbin:/usr/local/bin:/usr/bin:/bin"

# Verify sfdisk is accessible
RUN which sfdisk && sfdisk --version

Core bootc Functions in Particle OS

1. Image Composition and Building

Container-to-OS Transformation: Particle OS uses bootc to convert standard OCI container images into bootable operating system images. The process begins with a Containerfile that defines the complete system stack.

Example Particle OS Image Build Process:

# Typical Particle OS Containerfile structure
FROM debian:trixie
RUN apt-get update && apt-get install -y \
    systemd \
    dbus \
    sudo \
    util-linux \  # CRITICAL: Provides sfdisk
    parted \
    e2fsprogs \
    dosfstools \
    grub-efi-amd64 \
    efibootmgr \
    # Desktop environment
    task-kde-desktop \
    # Applications
    firefox-esr \
    # ... other packages

# Critical: Create /home -> /var/home symlink for immutable architecture
RUN ln -sf ../var/home /home

# Set up OSTree configuration
RUN mkdir -p /etc/ostree
COPY ostree-config/ /etc/ostree/

# Add required bootc labels
LABEL ostree.bootable=true
LABEL ostree.version=2025.2
LABEL ostree.osname=debian-atomic

bootc Integration:

• bootc-image-builder: Converts the container image into various bootable formats
• GitHub Actions Integration: Automated builds triggered by repository changes
• Multi-architecture Support: Building images for x86_64, ARM64, and other architectures

2. System Installation and Deployment

Direct Installation: bootc provides the primary installation mechanism for Particle OS systems:

# Install Particle OS image directly to disk
sudo env PATH="/usr/sbin:/sbin:/usr/local/bin:/usr/bin:/bin" \
  podman run --rm --privileged --pid=host --volume /dev:/dev \
  localhost/debian-atomic:latest \
  /usr/bin/bootc install to-disk /dev/sda --filesystem ext4

Key Installation Features:

• Automated Partitioning: Creates proper GPT partition layout with EFI, boot, root, and /var partitions
• Immutable Root Setup: Configures OSTree-based immutable filesystem structure
• Bootloader Configuration: Installs and configures GRUB for atomic system management
• Network Installation: Downloads and applies container images directly from registries

3. System Updates and Maintenance

Atomic Updates: Particle OS systems update by pulling new container image versions:

# Update to latest image version
bootc upgrade

# Update to specific image version
bootc upgrade --image ghcr.io/particle-os/debian-atomic:2025.2.1

Update Characteristics:

• Transactional: Updates either succeed completely or fail without system changes
• Background Downloads: New images downloaded while system continues running
• Rollback Safety: Previous system state always available
• Registry-Based: Updates pulled from container registries rather than traditional repositories

4. System Rollback and Recovery

Rollback Mechanisms:

# List available system deployments
bootc status

# Rollback to previous deployment
apt-ostree rollback

# Boot into previous deployment (temporary)
# Select previous deployment from GRUB menu

Recovery Features:

• Automatic Rollback: System automatically reverts on boot failure
• Multiple Deployments: Keep several system versions simultaneously
• Instant Switching: Change between deployments with simple reboot

5. Custom Image Development

Particle OS as Base Images: Developers use Particle OS images as base layers for custom systems:

FROM ghcr.io/particle-os/debian-atomic:latest
RUN apt-get update && apt-get install -y \
    development-tools \
    additional-packages
COPY custom-config/ /etc/

Development Workflow:

• Local Building: podman build creates custom images
• Testing: bootc install deploys custom images for testing
• Distribution: Push custom images to container registries
• Deployment: Users install custom images same as official Particle OS releases

Specific Particle OS Image Variants and bootc Usage

Desktop-Focused Images

Standard Desktop Stack:

FROM debian:trixie
# Desktop environment packages
RUN apt-get install -y \
    task-kde-desktop \
    firefox-esr \
    libreoffice \
    # Desktop applications

bootc for Desktop Systems:

• Hardware-Specific Images: Different images for different hardware configurations
• Performance Optimization: Desktop-focused kernel parameters and configurations
• Application Integration: Pre-installed desktop applications and tools

Development Images

Developer-Focused Stack:

FROM debian:trixie
RUN apt-get install -y \
    podman \
    docker.io \
    code \
    nodejs \
    python3-dev \
    # Development tools

Development Features:

• Container Development: Pre-configured container runtimes
• IDE Integration: Visual Studio Code and development extensions
• Language Support: Multiple programming language runtimes

Server and Cloud Images

Minimal Server Deployments:

# Deploy Particle OS server image
sudo env PATH="/usr/sbin:/sbin:/usr/local/bin:/usr/bin:/bin" \
  podman run --rm --privileged --pid=host --volume /dev:/dev \
  localhost/particle-os-server:latest \
  /usr/bin/bootc install to-disk /dev/sda --filesystem ext4

Server Characteristics:

• Headless Operation: No desktop environment
• Container Runtime: Optimized for containerized workloads
• Remote Management: SSH and remote administration tools

Integration with Particle OS Infrastructure

CI/CD Pipeline Integration

Automated Building: Particle OS uses GitHub Actions with bootc for continuous integration:

# GitHub Actions workflow
- name: Build Image
  uses: redhat-actions/buildah-build@v2
  with:
    image: particle-os-debian-atomic
    tags: latest
    containerfiles: ./Containerfile

- name: Create Bootable Image
  run: |
    bootc-image-builder \
      --type qcow2 \
      --output ./output/ \
      ghcr.io/particle-os/debian-atomic:latest

Release Management:

• Automated Testing: bootc deploys images to test environments
• Version Tagging: Images tagged with semantic versions
• Registry Publishing: Built images pushed to GitHub Container Registry

Update Distribution

Registry-Based Updates: Particle OS distributes updates through container registries:

• ghcr.io/particle-os/: Primary registry for official images
• Automated Rebuilds: Images rebuilt on upstream Debian updates
• Security Updates: Rapid deployment of security patches through container layers

Hardware Support Integration

Driver Integration:

# Hardware-specific image variants
FROM ghcr.io/particle-os/base:latest
# NVIDIA driver integration
COPY --from=nvidia-driver-image /usr/lib/modules/ /usr/lib/modules/
RUN apt-get install -y nvidia-driver

Hardware-Specific Deployment:

• Automatic Detection: bootc can select appropriate image based on hardware
• Driver Packaging: Kernel modules packaged in container layers
• Hardware Variants: Separate images for different hardware configurations

Advanced bootc Features in Particle OS

Multi-Architecture Support

Cross-Platform Building:

# Build for multiple architectures
podman build --platform linux/amd64,linux/arm64 \
  -t ghcr.io/particle-os/multiarch:latest .

# Deploy on ARM64 systems
sudo env PATH="/usr/sbin:/sbin:/usr/local/bin:/usr/bin:/bin" \
  podman run --rm --privileged --pid=host --volume /dev:/dev \
  localhost/particle-os-multiarch:latest \
  /usr/bin/bootc install to-disk /dev/mmcblk0 --filesystem ext4

Architecture Support:

• x86_64: Primary desktop and laptop support
• ARM64: Support for ARM-based systems and single-board computers
• RISC-V: Experimental support for RISC-V hardware

Network Boot and PXE Integration

Network Installation:

# Network boot configuration
sudo env PATH="/usr/sbin:/sbin:/usr/local/bin:/usr/bin:/bin" \
  podman run --rm --privileged --pid=host --volume /dev:/dev \
  localhost/particle-os:latest \
  /usr/bin/bootc install to-disk /dev/sda --filesystem ext4 --via-kargs

Enterprise Features:

• PXE Boot Support: Network booting for enterprise deployments
• Unattended Installation: Scripted installations for mass deployment
• Configuration Management: Integration with enterprise configuration systems

Development and Testing Workflows

Local Development:

# Build local custom image
podman build -t local/particle-os-custom .

# Test with bootc
sudo env PATH="/usr/sbin:/sbin:/usr/local/bin:/usr/bin:/bin" \
  podman run --rm --privileged --pid=host --volume /dev:/dev \
  localhost/particle-os-custom:latest \
  /usr/bin/bootc install to-disk /dev/vdb --filesystem ext4

Development Features:

• Local Registry Support: bootc works with local container registries
• Development Mode: Install images without signature verification
• Rapid Iteration: Quick build-test-deploy cycles for development

Integration with Existing Debian Infrastructure

Package Management Integration

apt-ostree Compatibility: bootc images built with apt-ostree maintain compatibility:

# Layer additional packages on running system
apt-ostree install additional-package

# Reboot into new deployment
systemctl reboot

Layering vs. Container Updates:

• Container Updates: Major system changes delivered via new bootc images
• apt-ostree Layering: Minor package additions and user customizations
• Hybrid Approach: Combines benefits of both deployment methods

Desktop Environment Integration

KDE and GNOME Support: bootc images include complete desktop environments:

• Session Management: Desktop sessions work normally with immutable base
• User Applications: Flatpak integration for user application installation
• System Settings: Desktop settings persist across system updates in /var

Container Runtime Integration

Podman and Docker: Particle OS images include container runtimes:

# Container runtimes available immediately after bootc installation
podman run hello-world
docker run hello-world

Development Workflows:

• Distrobox Integration: Development environments in containers
• Toolbox Support: Debian toolbox containers for development
• OCI Ecosystem: Full compatibility with container ecosystem

Security and Verification

Image Signing and Verification

Cosign Integration: Particle OS images are signed with cosign:

# Verify image signature before installation
cosign verify ghcr.io/particle-os/debian-atomic:latest

# Install with signature verification
sudo env PATH="/usr/sbin:/sbin:/usr/local/bin:/usr/bin:/bin" \
  podman run --rm --privileged --pid=host --volume /dev:/dev \
  --verify-signature \
  localhost/debian-atomic:latest \
  /usr/bin/bootc install to-disk /dev/sda --filesystem ext4

Security Features:

• Supply Chain Security: Signed container images ensure authenticity
• SBOM Generation: Software Bill of Materials for transparency
• Reproducible Builds: Consistent builds for security verification

Secure Boot Support

UEFI Secure Boot: bootc-installed systems support Secure Boot:

• Signed Kernels: Kernel and modules signed for Secure Boot
• Bootloader Security: GRUB configured for Secure Boot environments
• TPM Integration: Trusted Platform Module support for measured boot

Performance and Optimization

Storage Efficiency

OSTree Deduplication: bootc leverages OSTree's storage efficiency:

• Hardlink Optimization: Identical files shared between deployments
• Delta Updates: Only changed files transferred during updates
• Compression: Efficient storage of system images

Network Optimization

Bandwidth-Conscious Updates:

• Layer Caching: Container layers cached locally to minimize downloads
• Incremental Updates: Only new layers downloaded during updates
• CDN Distribution: Images distributed via content delivery networks

Troubleshooting Common Issues

Disk Utility Problems

Issue: error: Installing to disk: Creating rootfs: Failed to run sfdisk: No such file or directory

Diagnosis Steps:

# 1. Check if util-linux is installed
dpkg -l | grep util-linux

# 2. Find sfdisk binary location
find / -name sfdisk 2>/dev/null

# 3. Check current PATH
echo $PATH

# 4. Test sfdisk directly
/usr/sbin/sfdisk --version

Common Solutions:

1. Missing util-linux: sudo apt install util-linux
2. PATH issue: export PATH="/usr/sbin:/sbin:$PATH"
3. Minimal environment: Use explicit PATH in bootc command
4. Container environment: Ensure container image includes disk utilities

UTF-8 Encoding Issues

Issue: Linkname can't be converted from UTF-8 to current locale

Solution:

# In Containerfile
ENV LANG=C.UTF-8
ENV LC_ALL=C.UTF-8
RUN apt-get install -y locales
RUN locale-gen C.UTF-8

Kernel Detection Issues

Issue: Failed to find kernel in /usr/lib/modules, /usr/lib/ostree-boot or /boot

Solution:

# In Containerfile
RUN apt-get install -y linux-image-amd64 linux-headers-amd64

# Create ostree-boot directory and copy kernel files
RUN mkdir -p /usr/lib/ostree-boot
RUN cp /boot/vmlinuz-$(uname -r) /usr/lib/ostree-boot/vmlinuz
RUN cp /boot/initrd.img-$(uname -r) /usr/lib/ostree-boot/initramfs.img
RUN cp -r /usr/lib/modules/$(uname -r) /usr/lib/ostree-boot/modules

Future Directions and Roadmap

Emerging Features

Planned bootc Enhancements:

• Live Updates: System updates without requiring reboots
• Bootloader Integration: Enhanced bootloader management
• Hardware Abstraction: Better hardware detection and driver integration

Particle OS Evolution

Platform Development:

• Expanded Hardware Support: More device and architecture support
• Enterprise Features: Enhanced management and deployment tools
• Community Growth: Broader ecosystem of custom images and variants

Conclusion

bootc serves as the foundational technology enabling Particle OS's vision of reliable, maintainable, and user-friendly atomic desktop systems based on Debian. Through its comprehensive approach to container-based operating system deployment, bootc transforms how users install, update, and manage their desktop Linux systems.

The integration of bootc into every aspect of the Particle OS workflow—from initial image composition through daily system maintenance—demonstrates the power of treating operating systems as immutable, versioned artifacts. This approach provides unprecedented reliability and consistency while maintaining the flexibility and functionality users expect from modern desktop environments.

As bootc and Particle OS continue to evolve, they represent a significant advancement in operating system design, offering a glimpse into the future of Linux desktop computing where system administration becomes dramatically simpler and more reliable.

Critical Success Factors for Particle OS:

• All deployment environments must include complete disk utility sets
• Atomic images must contain all necessary partitioning and filesystem creation tools
• Testing must validate that deployment environments have required utilities available
• Documentation must clearly communicate disk utility requirements to users and contributors