particle-os/scope.md

Project Scope: Particle OS (Updated)

Vision: To create Particle OS, a robust, immutable, and opinionated Debian-based desktop operating system. By adopting the same tooling and workflow as ublue-os, the project aims to deliver a reliable, just-works experience with transactional updates and seamless rollback capabilities, all built on the stable foundation of Debian. The initial focus is on delivering a complete, functional product using open-source drivers, with proprietary hardware support as a future enhancement.

Architectural Foundation: Understanding Immutable Filesystem Design

The filesystem architecture of Particle OS is built on modern immutable system principles using OSTree technology and strategic application of the Filesystem Hierarchy Standard (FHS). This design separates the system into distinct layers:

• Immutable Root (/): The entire base system including /bin, /sbin, /lib, /usr, and base /etc templates are read-only, preventing corruption and enabling atomic updates
• Writable Overlays: Strategic writable spaces in /var (for logs, caches, container data) and /etc (for configuration management through three-way merge)
• User Data Redirection: Home directories physically stored in /var/home with symbolic link redirection from /home to maintain compatibility

This architecture enables atomic updates, reliable rollbacks, and system stability while supporting normal desktop workflows. For detailed technical information, see filesystem.md.

Critical Implementation Requirements: Disk Utilities and bootc Dependencies

⚠️ CRITICAL: The successful deployment of Particle OS using bootc install to-disk requires specific disk utilities that are often missing from minimal environments. This is a fundamental implementation requirement that must be addressed in all deployment scenarios.

Essential Disk Utilities for bootc Deployment

sfdisk (from util-linux): The most critical dependency for bootc's automated partitioning process. bootc uses sfdisk to:

• Create GPT partition tables for UEFI systems
• Automatically partition disks with the correct layout:
  • EFI System Partition (ESP) for UEFI boot
  • Boot partition for kernel/initramfs storage
  • Root partition for the immutable OSTree filesystem
  • /var partition for writable data (critical for immutable architecture)
• Script partition creation without user interaction

Other Required Utilities:

• parted - Alternative partitioning tool (fallback)
• mkfs.ext4 - Filesystem creation for root and /var partitions
• mkfs.fat - FAT32 filesystem for EFI partition
• grub-install - Bootloader installation
• efibootmgr - UEFI boot manager configuration

Deployment Environment Requirements

Live Environment Considerations:

• Minimal live ISOs often lack complete disk utilities
• Server/minimal installations may exclude util-linux or other essential packages
• Container environments must include these utilities in the deployment image

VM/Testing Environment Requirements:

• Ensure util-linux package is installed: sudo apt install util-linux
• Verify sfdisk availability: which sfdisk && sfdisk --version
• Check disk device visibility: lsblk and proper device permissions

Common Failure Points:

• error: Installing to disk: Creating rootfs: Failed to run sfdisk: No such file or directory
• Missing filesystem creation tools
• Incomplete bootloader installation utilities

Implementation Solutions

1. Atomic Image Requirements:

# Containerfile must include essential disk utilities
RUN apt-get install -y \
    util-linux \  # Provides sfdisk
    parted \
    e2fsprogs \   # Provides mkfs.ext4
    dosfstools \  # Provides mkfs.fat
    grub-efi-amd64 \
    efibootmgr

2. Live Environment Preparation:

# Ensure deployment environment has required utilities
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

3. Container-Based Deployment:

# Use containers with complete utility sets
podman run --privileged --pid=host --volume /dev:/dev \
  --image your-atomic-image:latest \
  bootc install to-disk /dev/target-device

4. PATH Environment Issues (Common in Minimal Environments):

# Critical: Ensure PATH includes /usr/sbin and /sbin
# Some minimal environments (VMs, containers) may have incomplete PATH
export PATH="/usr/sbin:/sbin:$PATH"

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

# Run bootc with explicit PATH
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

Troubleshooting Common Issues

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
/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

This requirement is fundamental to the success of Phase 1 and affects all subsequent phases. Proper documentation and testing of disk utility availability is essential for reliable deployment.

Implementation Challenges and Considerations

Building Particle OS on this immutable foundation presents several critical implementation challenges:

Toolchain Maturity: Unlike Fedora's mature rpm-ostree ecosystem, Debian-based immutable systems using apt-ostree and bootc represent newer territory with fewer community examples and potential edge cases.

Configuration Management: The /etc three-way merge system requires careful implementation and testing, especially for complex desktop environment configurations and system services.

Build Complexity: Every system update, particularly kernel updates, triggers complex dependency chains (kernel → drivers → full system rebuild) that must be automated and validated.

Testing Requirements: Beyond functional testing, the system requires validation of atomic updates, rollback mechanisms, and configuration merge behavior across update scenarios.

Disk Utility Dependencies: The critical requirement for sfdisk and related disk utilities in deployment environments represents a significant implementation challenge that must be addressed in all deployment scenarios.

Key Tools & Philosophy

• bootc: The central tool for building, deploying, and managing bootable OCI container images
• apt-ostree: The underlying technology for package management within the OSTree
• podman: The container runtime for all image building
• just scripts (justfile): The command runner for automating the entire pipeline
• xorriso: The standard, distro-agnostic tool for creating bootable ISO images
• Calamares: The graphical installer

---

Revised Roadmap: Building Particle OS

This roadmap acknowledges the implementation complexity of immutable systems while providing a clear path from theory to working product.

---

Phase 1: Minimal Debian Atomic Base (The Foundation)

Goal: Establish a bare-bones, bootable Debian system as an immutable OSTree image.

Critical Implementation Focus: Verify that the fundamental immutable architecture works with Debian tooling.

Tools: bootc, apt-ostree, podman, just

Steps:

1. Project Setup: Initialize a Git repository for particle-os. Create the Containerfile and justfile.
2. Define the Base Image (Containerfile):
   • Use a minimal Debian image (FROM debian:trixie).
   • Use apt-get to install the absolute minimum packages for a bootable system (e.g., systemd, dbus, sudo, apt, initramfs-tools).
   • Critical: Explicitly create the /home -> /var/home symbolic link with RUN ln -sf ../var/home /home.
3. Automated Build (justfile):
   • Create a just recipe (just build-base-image) that uses podman build -t particle-os-base:latest . to create your initial OCI image.
4. Initial Boot Test:
   • Create a just recipe (just test-base-image-vm) to deploy and boot this minimal image in a VM using bootc install to-disk.
   • Validation: Verify that you can boot to a command-line prompt and that /var is writable while the root filesystem is immutable.
   • Critical Test: Confirm that the /etc merge mechanism works with basic system configurations.

Deliverable: A functional, minimal Debian Atomic base image with verified immutable properties, buildable and testable via just.

Key Challenge: This phase validates that apt-ostree and bootc work reliably with Debian, establishing the foundation for all subsequent work.

---

Phase 2: Core Desktop Environment Integration

Goal: Transform the minimal base into a usable graphical desktop system while maintaining immutable properties.

Critical Implementation Focus: Ensure desktop environment packages and configurations work within the immutable architecture constraints.

Tools: bootc, apt-ostree, podman, just

Steps:

1. Extend Containerfile for Desktop:
   • Modify your Containerfile from Phase 1 to install your chosen desktop environment and its core components (e.g., task-kde-desktop or task-gnome-desktop, a display manager like sddm or gdm3).
   • Include essential graphical utilities and basic applications that are part of the desktop meta-package.
   • Critical: Handle desktop environment configurations that may expect to write to traditionally immutable locations.
2. Update Build Recipes:
   • Adjust your just build-image recipe to build this new desktop image (e.g., particle-os-desktop:latest).
   • Add validation recipes: just test-rollback to verify atomic update mechanisms work with the desktop stack.
3. Test Desktop Functionality:
   • Use a just recipe (e.g., just test-desktop-vm) to deploy and boot the new desktop image in a VM.
   • Comprehensive validation: Verify that the graphical desktop environment loads correctly, user sessions work properly, and system updates don't break desktop functionality.

Deliverable: A bootable Debian Atomic Desktop image with a working graphical environment that maintains immutable properties.

Key Challenge: Desktop environments often have complex configuration requirements and service dependencies that must work within immutable constraints.

---

Phase 3: Flatpak Integration & TUI Installer Testing

Goal: Integrate Flatpak support into your desktop image and create a robust testing framework for deployment logic.

Critical Implementation Focus: Validate that containerized applications work properly within the immutable host architecture.

Tools: bootc, just, bash scripting, podman

Steps:

1. Integrate Flatpak:
   • Modify your Containerfile from Phase 2 to install Flatpak (flatpak package).
   • Configure Flatpak repositories (e.g., Flathub) within the image.
   • Consider pre-installing a few essential Flatpak applications (e.g., a web browser, text editor) to demonstrate functionality.
   • Critical: Ensure Flatpak's use of /var/lib/flatpak integrates properly with the immutable architecture.
2. Create a TUI Installer Script:
   • Write a bash script (e.g., install.sh) that takes a bootc image tag as an argument.
   • This script will handle disk partitioning, formatting, and the core deployment command: bootc install to-disk --device /dev/sda --replace-os --image ....
   • Implementation Detail: Include proper error handling and validation of the deployment process.
3. Automate TUI Testing:
   • Add comprehensive just recipes for testing:
     • just test-tui-install-full-desktop - Basic installation testing
     • just test-update-rollback - Validate atomic update and rollback functionality
     • just test-flatpak-integration - Ensure containerized applications work correctly
   • Critical Testing: Validate that updates don't break Flatpak applications and that rollbacks restore full functionality.

Deliverable: A Debian Atomic Desktop image with validated Flatpak support and comprehensive automated testing of core deployment functionality.

Key Challenge: Container integration within immutable hosts requires careful validation of storage, permissions, and update behavior.

---

Phase 4: GUI Installer Integration (Calamares)

Goal: Integrate deployment logic into a full graphical installer to create a user-friendly ISO.

Critical Implementation Focus: Bridge the gap between low-level deployment validation and user-facing installation experience.

Tools: live-build, calamares, xorriso, just

Steps:

1. Live ISO Build Configuration (live-build):
   • Set up a live-build configuration to create a minimal live Debian system.
   • Include calamares and your validated installer script from Phase 3 in this live system.
   • Implementation Detail: Ensure the live environment has all necessary tools for deployment without conflicting with the target system.
2. Calamares Configuration:
   • Develop a custom Calamares configuration (YAML files) that instructs it to:
     • Handle partitioning compatible with immutable system requirements.
     • Use a post-install module to call your validated install.sh script.
   • Critical: Ensure error handling and user feedback during the immutable system deployment process.
3. Automate ISO Creation (justfile):
   • Create a just recipe (just build-iso) that orchestrates the live-build process and then uses xorriso to create the final .iso file.
   • Validation recipe: just test-iso-vm with comprehensive testing of the GUI installation process.
4. Installer Testing:
   • Add comprehensive testing recipes that validate not just successful installation, but proper handling of edge cases and error conditions.

Deliverable: A bootable Particle OS installer ISO that reliably deploys the atomic desktop image through a user-friendly graphical interface.

Key Challenge: Integrating immutable system deployment complexity with user-friendly installer interfaces while maintaining reliability.

---

Phase 5: Opinionated Customization & Distribution

Goal: Refine the user experience of Particle OS and establish a production-ready continuous delivery pipeline.

Critical Implementation Focus: Create a sustainable development and distribution workflow that handles the complexity of immutable system updates.

Tools: podman, just, GitHub Actions, comprehensive documentation

Steps:

1. Finalize Particle OS Customization:
   • Modify your desktop Containerfile to add all "opinionated" customizations: default applications, themes, icons, fonts, and custom configurations.
   • Implementation Detail: Ensure customizations don't conflict with immutable architecture or update mechanisms.
2. Implement ujust Commands:
   • Create a justfile that is copied into the final Particle OS image (e.g., to /usr/share/ujust/).
   • Define convenient ujust recipes for common user tasks (e.g., ujust update, ujust install-dev-tools).
   • Critical: Include user-facing commands for system management that work within immutable constraints.
3. Continuous Delivery with GitHub Actions:
   • Set up a GitHub Actions workflow to automatically build and push the particle-os:latest image to a container registry (e.g., ghcr.io) on a schedule or upon code changes.
   • Implementation Detail: Include automated testing of build artifacts before publishing.
   • Critical: Establish versioning strategy that tracks both base system updates and customization changes.
4. Documentation & Community:
   • Create comprehensive documentation covering:
     • Installation procedures and system requirements
     • ujust command reference and system management
     • Troubleshooting guide for immutable system concepts
     • Architecture documentation referencing filesystem.md

Deliverable: A production-ready, continuously delivered Particle OS with comprehensive documentation and sustainable maintenance workflows.

Key Challenge: Establishing reliable continuous delivery for immutable systems requires sophisticated automation and testing to handle complex update dependencies.

---

Stretch Goal: Advanced Features (Kernel Modules)

Goal: Implement a robust, build-time solution for proprietary kernel modules (e.g., NVIDIA drivers) to support specialized hardware.

Critical Implementation Focus: Handle the complex dependency chain of kernel updates triggering driver rebuilds and full system recomposition.

Tools: Dedicated kmods repository, multi-stage Containerfile builds, GitHub Actions

Steps:

1. Kmods Pipeline (ublue-os style):
   • Create a dedicated kmods repository with a Containerfile that builds the NVIDIA driver from source for specific Debian kernel versions.
   • Use GitHub Actions to automate the build of kernel module images and push them to a container registry.
   • Critical Implementation: Establish automated triggering when new kernels are available in Debian repositories.
2. Integrate kmods into Particle OS:
   • Modify your main Particle OS Containerfile to use multi-stage builds. The first stage sources from your nvidia-kmod image, and the second stage copies the pre-compiled kernel modules into the final filesystem.
   • Implementation Detail: Handle version alignment between kernel modules and system kernels.
3. Release a particle-os-nvidia Variant:
   • Create separate just recipes and Containerfile for the NVIDIA variant of Particle OS.
   • Critical: Ensure clear separation and labeling to avoid confusion between variants.
   • Testing: Establish automated testing for hardware-specific functionality where possible.

Deliverable: A specialized particle-os-nvidia image that provides out-of-the-box support for proprietary drivers with automated maintenance.

Key Challenge: Managing the complex build dependencies and timing between kernel updates, driver compilation, and system image composition while maintaining system stability.

---

Success Criteria and Risk Mitigation

Technical Success Criteria:

• Reliable atomic updates and rollbacks across all system components
• Seamless desktop environment functionality within immutable constraints
• Robust container application integration (Flatpak)
• User-friendly installation and system management experience

Risk Mitigation:

• Comprehensive automated testing at each phase to catch integration issues early
• Clear documentation of architectural decisions and implementation details
• Fallback strategies for complex features (e.g., manual driver installation if automatic kmods fail)
• Community engagement and feedback collection throughout development

This roadmap acknowledges that building an immutable desktop system involves not just understanding the architecture, but successfully implementing complex toolchain integration and handling the practical challenges that theory alone cannot address.