particle-os-tools/particle-os.md

Particle-OS: Desktop-First Immutable Ubuntu System

Overview

Particle-OS is an immutable Ubuntu-based desktop system inspired by uBlue-OS, designed specifically for desktop users who want the benefits of atomic updates, rollback capabilities, and system integrity without the complexity of cloud-native tooling.

Mission

Create a desktop-first immutable Ubuntu system that provides:

• Simple desktop experience - No cloud complexity, just a great desktop OS
• Atomic updates with rollback - Safe system updates with easy recovery
• uBlue-OS inspiration - Familiar patterns for users coming from Fedora-based immutable systems
• Ubuntu ecosystem - Full compatibility with Ubuntu software and repositories
• Gaming and productivity focus - Optimized for real desktop workloads

Desktop-First Philosophy

Particle-OS is built with a simple philosophy: desktop computing should be simple, powerful, and reliable. We reject the complexity of cloud-native tooling for desktop users and focus on what matters most:

• Real desktop workloads - Gaming, development, creativity, productivity
• Familiar workflows - Standard desktop applications and tools
• System reliability - Atomic updates with easy rollback
• User control - Easy customization and system management

Particle-OS Architecture

pcore - Particle-OS Core (ucore Equivalent)

pcore is Particle-OS's foundational base image, equivalent to uBlue-OS's ucore. It provides the minimal, immutable foundation that all Particle-OS desktop variants build upon.

pcore Features:

• Minimal Ubuntu Foundation: Clean Ubuntu base optimized for desktop use
• Desktop Framework: Essential desktop environment support and systemd services
• Atomic Update System: apt-layer integration for atomic package management
• Immutable Filesystem: Official ComposeFS tools for layered, immutable storage
• Boot Management: bootupd-alternative for UEFI and GRUB integration
• Desktop-Ready Base: Pre-configured for desktop workloads and user sessions

pcore Architecture:

pcore/
├── ubuntu-minimal-base     # Minimal Ubuntu 24.04 foundation
├── desktop-framework       # Desktop environment support
├── atomic-update-system    # apt-layer integration
├── immutable-filesystem    # Official ComposeFS tools
├── boot-management         # bootupd-alternative
└── systemd-services        # Desktop-optimized systemd configuration

pcore Benefits:

• Consistent Foundation: All desktop variants share the same reliable base
• Atomic Updates: Full system atomicity with rollback capabilities
• Desktop Optimization: Built specifically for desktop workloads
• Simple Architecture: No cloud complexity, desktop-first design
• Ubuntu Compatibility: Full compatibility with Ubuntu ecosystem

Core Components

apt-layer - Atomic Package Management

Ubuntu package management with atomic transactions, live overlay system, rollback capabilities, and now true atomic OSTree commits per package operation. The new workflow supports offline .deb install, robust overlay system, and DNS fixes for WSL environments. Official ComposeFS tools are used for all image creation and mounting.

Key Features:

• Atomic package installation and updates
• Live overlay system for safe operations
• Automatic rollback on failures
• Desktop-friendly package management
• Integration with Ubuntu repositories
• OSTree atomic commits - True atomic package management with versioned history
• Offline .deb support - Install packages without network dependency
• Robust overlay system - DNS fixes for WSL, comprehensive error handling

Usage:

# Install software (rpm-ostree style)
apt-layer.sh install steam wine lutris

# Atomic OSTree package management
apt-layer.sh ostree compose install firefox vlc
apt-layer.sh ostree compose remove package-name
apt-layer.sh ostree compose update

# View atomic history
apt-layer.sh ostree log
apt-layer.sh ostree diff commit1 commit2
apt-layer.sh ostree rollback commit-id

# Update system
apt-layer.sh update

# Rollback if needed
apt-layer.sh rollback

Official ComposeFS Integration - Layered Filesystem

Particle-OS integrates with official ComposeFS tools from the containers community, providing content-addressable layered filesystem with production-ready performance and security.

Key Features:

• Official ComposeFS Tools: Uses mkcomposefs and mount.composefs from upstream
• Production Ready: Native C implementation with kernel optimizations
• Security: fs-verity support for filesystem integrity verification
• Performance: Page cache sharing and EROFS integration
• Standards Compliant: Full compliance with official ComposeFS specification
• Ecosystem Integration: Better integration with OSTree, Podman, and Flatpak

Status:

• ✅ Official Tools Working: Successfully tested and functional
• ✅ Automatic Backend Selection: Detects and uses official tools when available
• ✅ Fallback Support: Alternative implementation available if needed
• ⏳ Package Status: Ready for Debian/Ubuntu upload (awaiting sponsorship)

Usage:

# Install official tools (when available)
sudo apt install composefs-tools

# Or install from source
composefs-alternative.sh --official-install

# Mount desktop image
composefs-alternative.sh mount desktop-image /mnt/point

# Create new layer
composefs-alternative.sh create-layer gaming-packages

# List layers
composefs-alternative.sh list-layers

bootupd-alternative - Bootloader Management

UEFI and GRUB integration for desktop systems with multi-boot support.

Key Features:

• UEFI and GRUB integration
• Multi-boot support for dual-boot scenarios
• Desktop-friendly boot configuration
• Recovery options
• Secure boot support (optional)

Usage:

# Register desktop image
bootupd-alternative.sh register desktop-image

# Update bootloader
bootupd-alternative.sh update

# List boot entries
bootupd-alternative.sh list

Desktop Images

All Particle-OS desktop images are built on top of pcore, following the same pattern as uBlue-OS variants built on ucore:

Particle-OS Corona (KDE Plasma) - Aurora Equivalent

pcore + KDE Plasma + Gaming Tools

A radiant and expansive desktop experience with KDE Plasma, optimized for gaming and multimedia.

Features:

• KDE Plasma desktop environment
• Gaming optimizations (Steam, Wine, Lutris)
• Multimedia support (VLC, Kodi)
• Productivity tools (LibreOffice, Firefox)
• Gaming performance tuning
• Atomic updates with rollback

Target Users:

• Gamers and multimedia enthusiasts
• KDE Plasma fans
• Users who want a feature-rich desktop

Particle-OS Apex (GNOME) - Bluefin Equivalent

pcore + GNOME + Development Tools

A nimble, powerful, and adaptable desktop for power users with GNOME.

Features:

• GNOME desktop environment
• Development tools (VS Code, Docker, Git)
• Container and cloud development support
• Enterprise compliance features
• Development workflow optimization
• Atomic updates with rollback

Target Users:

• Developers and power users
• GNOME enthusiasts
• Users who need development tools

Particle-OS Bazzite (Gaming-Focused) - Bazzite Equivalent (Planned)

pcore + Dual Desktop + Steam Mode

A gaming-focused system with dual desktop support and Steam mode.

Features:

• Dual desktop support (KDE Plasma + GNOME)
• Steam mode for gaming optimization
• Gaming performance tuning
• Steam, Wine, and Lutris integration
• Gaming-focused kernel parameters
• Atomic updates with rollback

Target Users:

• Serious gamers
• Users who want maximum gaming performance
• Users who want desktop flexibility

Desktop-First Design Principles

1. Simplicity First

• No cloud complexity
• Familiar desktop workflows
• Easy-to-understand tools
• Minimal learning curve

2. Desktop Performance

• Optimized for desktop workloads
• Fast boot times
• Responsive desktop experience
• Gaming performance focus

3. User Control

• Easy system customization
• Simple package management
• Transparent system operations
• User-friendly tools

4. Reliability

• Atomic updates prevent system corruption
• Easy rollback when things go wrong
• System integrity protection
• Stable desktop experience

Technical Architecture

Package Management Flow

# Desktop-friendly package installation
apt-layer.sh install steam wine lutris
├── Transaction Start
│   ├── Validate dependencies
│   ├── Check disk space
│   └── Create transaction manifest
├── Safe Installation
│   ├── Install packages atomically
│   ├── Preserve system integrity
│   └── Generate layer manifest
├── Desktop Integration
│   ├── Update desktop menus
│   ├── Configure desktop shortcuts
│   └── Set up user preferences
└── Commit or Rollback
    ├── Commit successful installation
    ├── Update system state
    └── Clean up temporary files

Atomic OSTree Workflow

# True atomic package management with OSTree
apt-layer.sh ostree compose install firefox vlc
├── OSTree Commit Creation
│   ├── Create atomic transaction
│   ├── Install packages in overlay
│   ├── Generate OSTree commit
│   └── Update deployment database
├── Atomic Deployment
│   ├── Set pending deployment
│   ├── Preserve rollback capability
│   └── Maintain system integrity
└── Versioned History
    ├── Track package changes
    ├── Maintain commit history
    └── Enable atomic rollback

Filesystem Architecture

# Desktop-optimized layered filesystem
composefs-alternative.sh mount desktop-image /mnt/point
├── Layer Discovery
│   ├── Read desktop layer manifest
│   ├── Validate layer integrity
│   └── Determine mount order
├── Desktop Layer Mounting
│   ├── Mount base Ubuntu layer
│   ├── Mount desktop environment layer
│   ├── Mount user applications layer
│   └── Create overlayfs for user data
└── Desktop Integration
    ├── Configure desktop environment
    ├── Set up user preferences
    └── Enable desktop features

Boot Management

# Desktop-friendly boot management
bootupd-alternative.sh register desktop-image
├── UEFI Integration
│   ├── Create UEFI boot entry
│   ├── Set boot order
│   └── Configure secure boot (optional)
├── GRUB Configuration
│   ├── Generate desktop-friendly menu
│   ├── Add recovery options
│   └── Configure timeout settings
└── Desktop Boot
    ├── Fast boot to desktop
    ├── Load desktop environment
    └── Start user session

Desktop Use Cases

1. Gaming Desktop

• Steam, Epic Games, GOG integration
• Wine and Proton support
• Gaming performance optimization
• Multi-monitor gaming support
• Gaming peripheral support

2. Development Workstation

• VS Code, IntelliJ, Eclipse support
• Docker and container development
• Git and version control
• Database development tools
• Web development environment

3. Creative Workstation

• GIMP, Inkscape, Blender support
• Video editing tools
• Audio production software
• Photography workflow tools
• Design and illustration software

4. Productivity Desktop

• Office suite integration
• Email and calendar tools
• Web browsing and communication
• File management and backup
• Personal productivity tools

Installation and Setup

Simple Installation

# Download Particle-OS ISO
wget https://particle-os.org/downloads/particle-os-corona-24.04.iso

# Create bootable USB
sudo dd if=particle-os-corona-24.04.iso of=/dev/sdX bs=4M status=progress

# Boot and install
# Follow simple installation wizard
# Choose desktop preferences
# Set up user account

Post-Installation Setup

# Install additional software
apt-layer.sh install firefox libreoffice vlc

# Configure gaming (for Corona)
apt-layer.sh install steam wine lutris

# Configure development (for Apex)
apt-layer.sh install code docker git

# Use atomic OSTree package management
apt-layer.sh ostree compose install firefox vlc
apt-layer.sh ostree compose update

# Customize desktop
# Configure themes and icons
# Set up user preferences
# Configure gaming peripherals

System Management

Package Management

# Install software (rpm-ostree style)
apt-layer.sh install package-name

# Atomic OSTree package management
apt-layer.sh ostree compose install package-name
apt-layer.sh ostree compose remove package-name
apt-layer.sh ostree compose update

# View atomic history
apt-layer.sh ostree log
apt-layer.sh ostree diff commit1 commit2
apt-layer.sh ostree status

# Update system
apt-layer.sh update

# Remove software
apt-layer.sh remove package-name

# List installed packages
apt-layer.sh list

# Search for packages
apt-layer.sh search package-name

System Updates

# Check for updates
apt-layer.sh check-updates

# Apply updates atomically
apt-layer.sh update-system

# Rollback if needed
apt-layer.sh rollback

# View update history
apt-layer.sh history

System Recovery

# Boot to recovery mode
# Select recovery option from GRUB menu

# Reset to factory state
apt-layer.sh factory-reset

# Restore from backup
apt-layer.sh restore-backup

# Repair system
apt-layer.sh repair-system

Desktop Customization

Theme and Appearance

• Easy theme switching
• Icon pack installation
• Desktop wallpaper management
• Desktop effects configuration
• Custom desktop layouts

Gaming Configuration

• Steam integration
• Wine prefix management
• Gaming performance tuning
• Multi-monitor gaming setup
• Gaming peripheral configuration

Development Environment

• IDE installation and configuration
• Development tool setup
• Container development environment
• Version control configuration
• Database development tools

Project Structure

particle-os/
├── tools/                    # Core system tools
│   ├── apt-layer.sh         # Atomic package management
│   ├── composefs-alternative.sh  # Layered filesystem
│   ├── bootupd-alternative.sh    # Bootloader management
│   └── particle-os-desktop/      # Desktop-specific tools
├── main/                     # Base Ubuntu image
├── kernel-cache/             # Ubuntu kernel caching
├── corona/                   # KDE Plasma desktop (Aurora equivalent)
├── apex/                     # GNOME desktop (Bluefin equivalent)
├── bazzite/                  # Gaming-focused desktop (Bazzite equivalent, planned)
└── infrastructure/           # Build infrastructure

Community and Support

Documentation

• User-friendly guides
• Desktop-specific tutorials
• Gaming setup guides
• Development environment guides
• Troubleshooting guides

Community Support

• Desktop-focused community
• Gaming community integration
• Developer community support
• User experience feedback
• Feature request system

Contributing

• Desktop-focused development
• User experience improvements
• Gaming optimizations
• Development tool integration
• Documentation contributions

Roadmap

Phase 1: Core Desktop Experience

• Stable Corona (KDE Plasma) release
• Stable Apex (GNOME) release
• Basic gaming support
• Development tool integration
• User documentation

Phase 2: Enhanced Desktop Features

• Bazzite (gaming-focused) release
• Advanced gaming optimizations
• Enhanced development tools
• Desktop customization tools
• Community features

Phase 3: Desktop Ecosystem

• Software center integration
• Theme and customization marketplace
• Gaming community features
• Developer tool marketplace
• Enterprise desktop features

Conclusion

Particle-OS is designed specifically for desktop users who want the benefits of immutable systems without the complexity of cloud-native tooling. By focusing on desktop-first design principles, we create a system that's:

• Simple to use - No cloud complexity
• Powerful for gaming - Optimized for desktop gaming
• Great for development - Full development tool support
• Reliable and safe - Atomic updates with rollback
• Familiar and comfortable - Based on Ubuntu ecosystem

This desktop-first approach ensures that Particle-OS remains focused on what matters most: providing an excellent desktop computing experience for real users doing real work and play.