Particle-OS Tools

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.

This repository contains the core tools that power Particle-OS, providing a complete immutable system solution for Ubuntu/Debian environments.

Core Tools Overview

apt-layer - Atomic Package Management

Ubuntu's answer to rpm-ostree - Atomic package management with OSTree commits, live overlay system, and rollback capabilities.

Key Features:

• Atomic OSTree Commits - True atomic package operations with versioned history
• Live Overlay System - Install packages without rebooting (rpm-ostree style)
• Container-based Layering - Apx-style isolation for secure package installation
• Direct dpkg Installation - Performance optimization for apt/deb systems
• OCI Integration - Export/import container images
• rpm-ostree Compatibility - Full command compatibility with rpm-ostree

Usage Examples:

# Install packages atomically
sudo apt-layer.sh install steam wine lutris

# Live system installation (no reboot required)
sudo apt-layer.sh --live-install firefox

# Atomic OSTree package management
sudo apt-layer.sh ostree compose install firefox vlc
sudo apt-layer.sh ostree log
sudo apt-layer.sh ostree rollback commit-id

# Container-based layer creation
sudo apt-layer.sh --container particle-os/base/24.04 particle-os/gaming/24.04 steam wine

# Direct dpkg installation (performance optimized)
sudo apt-layer.sh --dpkg-install curl wget

# System management
sudo apt-layer.sh status
sudo apt-layer.sh rollback
sudo apt-layer.sh cleanup

bootc-alternative - Container-Native Boot Management

Container-native bootable image management - Handles deployment, staging, rollback, and status reporting for immutable OS images.

Key Features:

• Container Image Validation - Validates container images for bootability
• Multi-bootloader Support - UEFI, GRUB, LILO, syslinux
• System Reinstallation - Complete system deployment capabilities
• Kernel Arguments Management - Dynamic kernel parameter configuration
• Secrets Management - Secure handling of authentication and secrets
• User Overlay Management - usroverlay support for user data

Usage Examples:

# Deploy container image to bootable system
sudo bootc-alternative.sh deploy container-image

# Check deployment status
sudo bootc-alternative.sh status

# Manage kernel arguments
sudo bootc-alternative.sh kargs add console=ttyS0
sudo bootc-alternative.sh kargs list

# System reinstallation
sudo bootc-alternative.sh install container-image

# Manage secrets
sudo bootc-alternative.sh secrets add my-secret secret-value
sudo bootc-alternative.sh secrets list

bootupd-alternative - Bootloader Management

Bootloader integration and configuration - Manages UEFI/GRUB entries, kernel arguments, and boot configuration for atomic OS deployments.

Key Features:

• UEFI Integration - Automatic UEFI boot entry management
• GRUB Configuration - Multi-boot GRUB menu generation
• Boot Entry Management - Add, remove, and configure boot entries
• Kernel Arguments - Dynamic kernel parameter management
• Recovery Options - Built-in recovery and emergency boot options
• Secure Boot Support - Optional secure boot integration

Usage Examples:

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

# Update bootloader configuration
sudo bootupd-alternative.sh update

# List boot entries
sudo bootupd-alternative.sh list

# Set default boot entry
sudo bootupd-alternative.sh set-default particle-os/gaming/24.04

# Add kernel arguments
sudo bootupd-alternative.sh kargs add rd.break=pre-mount

dracut-module.sh - Boot-Time Immutability

Boot-time immutable root filesystem - Provides true immutability at boot time using overlayfs and squashfs layers.

Key Features:

• Boot-Time Layer Mounting - Mounts squashfs layers at boot via initramfs
• Overlayfs Root - Creates immutable root filesystem using overlayfs
• Deterministic Ordering - Uses manifest.json for consistent layer ordering
• Fallback Support - OSTree deployment fallback when layers aren't available
• Security - Secure state directory and kernel parameter validation

Usage Examples:

# Install dracut module
sudo dracut-module.sh install

# Generate initramfs with Particle-OS support
sudo dracut-module.sh generate

# Update boot configuration
sudo dracut-module.sh update

# Check module status
sudo dracut-module.sh status

oci-integration.sh - Container Ecosystem Bridge

OCI container integration utilities - Seamless integration between Particle-OS and the container ecosystem.

Key Features:

• ComposeFS OCI Conversion - Bidirectional conversion between formats
• Registry Integration - Push/pull to container registries
• Container Runtime Support - Works with podman, docker, etc.
• Cleanup and Validation - Removes device files, validates images
• apt-layer Integration - Direct integration with apt-layer workflow

Usage Examples:

# Export apt-layer result to OCI
sudo oci-integration.sh export particle-os/gaming/24.04 particle-os/gaming:latest

# Import OCI image to apt-layer
sudo oci-integration.sh import ubuntu:24.04 particle-os/base/24.04

# Push to container registry
sudo oci-integration.sh push particle-os/gaming:latest docker.io/myregistry/gaming:latest

# Pull from container registry
sudo oci-integration.sh pull docker.io/myregistry/gaming:latest particle-os/gaming/24.04

particle-config.sh - Centralized Configuration

Centralized configuration management - Manages paths, settings, and system configuration across all Particle-OS tools.

Key Features:

• Unified Configuration - Single configuration file for all tools
• Environment Variables - Exports configuration for all scripts
• Path Management - Standardized paths across the system
• Feature Toggles - Enable/disable specific features
• Security Settings - Centralized security configuration

Configuration Example:

# Load configuration
source /usr/local/etc/particle-config.sh

# Key variables
WORKSPACE="/var/lib/particle-os"
COMPOSEFS_SCRIPT="/usr/local/bin/composefs-alternative.sh"
CONTAINER_RUNTIME="podman"
PARTICLE_LOG_LEVEL="info"

particle-logrotate.sh - Log Management

Log rotation and management - Ensures proper log file maintenance and prevents disk space issues.

Key Features:

• Automatic Log Rotation - Rotates logs based on size and time
• Compression - Compresses old log files to save space
• Retention Policies - Configurable retention periods
• Systemd Integration - Integrates with systemd journal
• Error Handling - Robust error handling and recovery

Usage Examples:

# Install log rotation configuration
sudo particle-logrotate.sh install

# Test log rotation
sudo particle-logrotate.sh test

# Check log status
sudo particle-logrotate.sh status

# Clean up old logs
sudo particle-logrotate.sh cleanup

System Architecture

Particle-OS Stack

apt-layer  ComposeFS  bootc-alternative  OCI Images
                         
dracut-module.sh    oci-integration.sh
                         
Boot-time immutability   Container ecosystem

Key Advantages

1. Live System Updates - Install packages without rebooting
2. Container Integration - Native OCI container support
3. Boot-Time Immutability - True immutable root at boot
4. Performance Optimization - Direct dpkg installation
5. Flexibility - Multiple backends (ComposeFS + OSTree fallback)
6. Extensibility - Modular scriptlet architecture

Installation

Quick Installation

# Clone the repository
git clone https://github.com/your-org/particle-os-tools.git
cd particle-os-tools

# Install all tools
sudo ./install-particle-os.sh

# Or install individual tools
sudo ./install-ubuntu-particle.sh

Development Installation

# Install development dependencies
sudo ./dev-install.sh

# Compile tools from source
cd src/apt-layer && ./compile.sh
cd src/bootc && ./compile.sh
cd src/bootupd && ./compile.sh

Usage Workflow

1. System Initialization

# Initialize Particle-OS system
sudo apt-layer.sh --init

# Configure bootloader
sudo bootupd-alternative.sh init

2. Package Management

# Install packages atomically
sudo apt-layer.sh install firefox libreoffice

# Live system installation
sudo apt-layer.sh --live-install steam wine

# View system status
sudo apt-layer.sh status

3. System Updates

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

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

# Rollback if needed
sudo apt-layer.sh rollback

4. Container Integration

# Export system to container image
sudo oci-integration.sh export particle-os/gaming/24.04 myregistry/gaming:latest

# Deploy container image
sudo bootc-alternative.sh deploy myregistry/gaming:latest

Configuration

System Configuration

All tools use the centralized configuration system via particle-config.sh:

# Main configuration file
/usr/local/etc/particle-config.sh

# Key configuration variables
WORKSPACE="/var/lib/particle-os"
COMPOSEFS_SCRIPT="/usr/local/bin/composefs-alternative.sh"
CONTAINER_RUNTIME="podman"
PARTICLE_LOG_LEVEL="info"

Tool-Specific Configuration

Each tool can have additional configuration files:

# apt-layer configuration
/etc/apt-layer/config/

# bootc-alternative configuration
/etc/bootc/config/

# bootupd-alternative configuration
/etc/bootupd/config/

Development

Source Code Structure

src/
 apt-layer/          # apt-layer source scriptlets
 bootc/             # bootc-alternative source scriptlets
 bootupd/           # bootupd-alternative source scriptlets
 mac-support/       # macOS support scripts

docs/                  # Project documentation
infrastructure/        # Infrastructure planning
containers/           # Container definitions

Compilation

All tools are compiled from modular scriptlets:

# Compile apt-layer
cd src/apt-layer && ./compile.sh

# Compile bootc-alternative
cd src/bootc && ./compile.sh

# Compile bootupd-alternative
cd src/bootupd && ./compile.sh

Testing

System Testing

# Run comprehensive system tests
sudo ./test-particle-os-system.sh

# Test individual tools
sudo ./test-apt-layer.sh
sudo ./test-bootc.sh
sudo ./test-bootupd.sh

Integration Testing

# Test complete workflow
sudo ./test-complete-workflow.sh

# Test rollback scenarios
sudo ./test-rollback-scenarios.sh

Troubleshooting

Common Issues

1. DNS Resolution in WSL

   # Fix DNS in chroot environment
   sudo chroot /var/lib/particle-os/live-overlay/mount bash -c "echo 'nameserver 8.8.8.8' > /etc/resolv.conf"
   

2. Bootloader Issues

   # Reinstall bootloader
   sudo bootupd-alternative.sh reinstall
   

3. Layer Mounting Problems

   # Check layer integrity
   sudo composefs-alternative.sh verify layer-name
   

Log Files

# View system logs
sudo journalctl -u particle-os

# View tool-specific logs
sudo tail -f /var/log/particle-os/apt-layer.log
sudo tail -f /var/log/particle-os/bootc.log

Contributing

Development Guidelines

1. Modular Architecture - Each tool uses scriptlet-based modular design
2. Error Handling - Comprehensive error handling and recovery
3. Logging - Unified logging system across all tools
4. Testing - Automated testing for all functionality
5. Documentation - Clear documentation and examples

Code Style

• Use bash scripting best practices
• Include comprehensive error handling
• Add logging for all operations
• Follow the established naming conventions
• Include usage examples and help text

License

This project is licensed under the MIT License - see the LICENSE file for details.

Support

Documentation

• Installation Guide
• Troubleshooting Guide
• API Documentation

Community

• GitHub Issues: Report bugs and request features
• Discussions: Community discussions

Development

• Contributing Guide: How to contribute
• Development Setup: Development environment

Roadmap

Phase 1: Core Stability

• Modular architecture implementation
• Transaction management system
• Traditional layer creation
• ComposeFS backend integration

Phase 2: Enhanced Features

• Container-based layer creation
• OCI integration
• Live system layering

Phase 3: Bootloader Integration

• Multi-bootloader support
• Kernel arguments management
• Boot entry management
• Atomic deployment integration

Phase 4: OSTree Atomic Package Management

• OSTree atomic commits for package operations
• Atomic deployment with rollback capabilities
• Versioned package history
• Direct dpkg installation optimization

Phase 5: Production Readiness

• Comprehensive testing suite
• Performance optimization
• Security hardening
• Enterprise features
• Documentation completion

Conclusion

Particle-OS tools provide a complete immutable system solution for Ubuntu/Debian environments, offering:

• Atomic package management with OSTree commits
• Live system updates without rebooting
• Container-native boot management
• Boot-time immutability for security
• OCI integration for container ecosystems
• Modular architecture for extensibility

These tools work together to create a robust, secure, and user-friendly immutable Ubuntu system that rivals the functionality of Fedora's uBlue-OS while maintaining Ubuntu's ease of use and software ecosystem.