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