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:**
```bash
# 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:**
```bash
# 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:**
```bash
# 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:**
```dockerfile
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:**
```dockerfile
# 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:

```bash
# 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:

```bash
# 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:**
```bash
# 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:

```dockerfile
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:**
```dockerfile
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:**
```dockerfile
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:**
```bash
# 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:

```yaml
# 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:**
```dockerfile
# 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:**
```bash
# 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:**
```bash
# 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:**
```bash
# 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:

```bash
# 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:

```bash
# 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:

```bash
# 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:**
```bash
# 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:**
```dockerfile
# 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:**
```dockerfile
# 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