particle-os-tools/Readme.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: composefs-alternative 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 22.04 foundation
├── desktop-framework       # Desktop environment support
├── atomic-update-system    # apt-layer integration
├── immutable-filesystem    # composefs-alternative
├── 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

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

Core Components

apt-layer - Atomic Package Management

Ubuntu package management with atomic transactions, live overlay system, and rollback capabilities.

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

Usage:

# Install software
apt-layer.sh install steam wine lutris

# 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

DKMS and NVIDIA Support

Particle-OS includes comprehensive DKMS (Dynamic Kernel Module Support) and NVIDIA driver support, following the successful patterns established by uBlue-OS. This enables users to install proprietary drivers, kernel modules, and other software that requires kernel compilation while maintaining the immutable system architecture.

DKMS Features:

• Atomic DKMS module installation and removal
• Automatic kernel module rebuilding on kernel updates
• Containerized DKMS builds for isolation
• Comprehensive DKMS module management
• Integration with Particle-OS atomic update system

NVIDIA Driver Support:

• NVIDIA driver installation via graphics-drivers PPA (recommended approach)
• Automatic driver version detection and recommendation
• NVIDIA Prime support for laptop GPU switching
• Gaming performance optimizations
• CUDA support for machine learning workloads

Usage:

# Install NVIDIA drivers (auto-detects optimal version)
apt-layer --nvidia-install auto

# Install specific DKMS module
apt-layer --dkms-install virtualbox-dkms 6.1.38

# Rebuild all DKMS modules after kernel update
apt-layer --dkms-rebuild-all

# Switch to NVIDIA GPU
apt-layer --gpu-switch nvidia

# Check DKMS status
apt-layer --dkms-status

# Check NVIDIA driver status
apt-layer --nvidia-status

Gaming Variants with NVIDIA Support:

• Particle-OS Bazzite Gaming (NVIDIA) - Ubuntu 25.04 with pre-installed NVIDIA drivers
• Particle-OS Corona Gaming (NVIDIA) - Ubuntu 24.04 LTS with KDE Plasma and NVIDIA support

Desktop Use Cases

Gaming Desktop

• Steam, Epic Games, GOG integration
• Wine and Proton support
• Gaming performance optimization
• Multi-monitor gaming support
• Gaming peripheral support
• NVIDIA driver support with DKMS
• Automatic GPU switching with NVIDIA Prime
• Gaming-focused kernel optimizations
• DKMS module support for gaming tools

Development Workstation

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

Creative Workstation

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

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

# Install NVIDIA drivers (if NVIDIA GPU detected)
apt-layer --nvidia-install auto

# Install DKMS modules for virtualization
apt-layer --dkms-install virtualbox-dkms 6.1.38

# Configure NVIDIA Prime for GPU switching
apt-layer --nvidia-prime-configure

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

System Management

Package Management

# Install software
apt-layer.sh install package-name

# 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
• NVIDIA driver configuration and optimization
• DKMS module management for gaming tools
• GPU switching with NVIDIA Prime
• Gaming-focused kernel parameter tuning

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
• DKMS and NVIDIA support - ✅ COMPLETED

Phase 2: Enhanced Desktop Features

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

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.