particle-os-tools/docs/README.md

Ubuntu uBlue Documentation

Overview

This directory contains comprehensive documentation for the Ubuntu uBlue system - a complete solution for immutable Ubuntu systems using ComposeFS, layer management, and container-native booting.

System Components

Core Scripts

apt-layer.sh

The core layer management tool for Ubuntu uBlue systems. Provides functionality similar to rpm-ostree for Fedora Silverblue/Kinoite.

Documentation: apt-layer/

bootloader-integration.sh

Provides integration between layer management and bootloader configuration, ensuring new layers are properly registered and bootable.

Documentation: bootupd/

composefs-alternative.sh

The immutable filesystem backend for Ubuntu uBlue systems, providing atomic, layered system updates using squashfs and overlayfs.

Documentation: composefs/

bootc-alternative.sh

Container-native bootable image system that allows running container images as bootable systems.

Documentation: bootc/

Supporting Scripts

oci-integration.sh

Provides OCI export/import functionality for ComposeFS images, enabling container registry integration.

ublue-config.sh

Unified configuration system providing consistent paths, logging, and settings across all Ubuntu uBlue scripts.

ublue-logrotate.sh

Log rotation utility for Ubuntu uBlue logs with configurable patterns and compression.

install-ubuntu-ublue.sh

Comprehensive installation script that sets up the entire Ubuntu uBlue system.

Documentation Structure

docs/
├── README.md                    # This file
├── apt-layer/                   # apt-layer.sh documentation
│   ├── README.md               # Overview and quick start
│   ├── apt-layer-guide.md      # Comprehensive user guide
│   ├── apt-layer-quickref.md   # Quick reference
│   ├── apt-layer-enhancements.md # Enhancement details
│   ├── transaction-flowchart.md # Transaction management
│   ├── INTEGRATION-SUMMARY.md  # Integration details
│   ├── AGGRESSIVE-SCRUTINY-RESPONSE.md # Security analysis
│   ├── FOLLOW-UP-IMPROVEMENTS.md # Follow-up fixes
│   └── IMPROVEMENTS-SUMMARY.md # Improvement summary
├── bootupd/                     # bootloader-integration.sh documentation
│   ├── README.md               # Overview and quick start
│   ├── bootloader-integration-guide.md # User guide
│   ├── bootloader-integration-api.md # API reference
│   ├── bootloader-security.md  # Security considerations
│   └── bootloader-troubleshooting.md # Troubleshooting
├── composefs/                   # composefs-alternative.sh documentation
│   ├── README.md               # Overview and quick start
│   ├── composefs-guide.md      # User guide
│   ├── composefs-api.md        # API reference
│   ├── composefs-architecture.md # Architecture details
│   ├── composefs-performance.md # Performance guide
│   ├── composefs-troubleshooting.md # Troubleshooting
│   └── composefs-migration.md  # Migration guide
└── bootc/                       # bootc-alternative.sh documentation
    ├── README.md               # Overview and quick start
    ├── bootc-guide.md          # User guide
    ├── bootc-api.md            # API reference
    ├── bootc-architecture.md   # Architecture details
    ├── bootc-performance.md    # Performance guide
    ├── bootc-troubleshooting.md # Troubleshooting
    └── bootc-migration.md      # Migration guide

Quick Start

Installation

# Install the complete Ubuntu uBlue system
sudo ./ubuntu_tools/install-ubuntu-ublue.sh

Basic Usage

# Create a new layer
apt-layer ubuntu-ublue/base/24.04 ubuntu-ublue/gaming/24.04 steam wine

# Install packages on live system
apt-layer --live-install steam wine

# Commit live changes
apt-layer --live-commit "Add gaming packages"

# Export as OCI image
apt-layer --oci-export ubuntu-ublue/gaming/24.04 ubuntu-ublue/gaming:latest

System Architecture

Ubuntu uBlue provides a complete immutable system solution:

1. ComposeFS Backend: Immutable filesystem using squashfs and overlayfs
2. Layer Management: Atomic layer creation and management with apt-layer.sh
3. Live Overlay: Temporary changes using overlayfs without rebooting
4. Boot Integration: Automatic bootloader integration for new layers
5. OCI Compatibility: Export/import layers as container images
6. Transaction Management: Atomic operations with rollback support

Key Features

• Immutable Design: System images cannot be modified at runtime
• Atomic Updates: All-or-nothing update semantics
• Live Layering: Install packages without rebooting
• Container Integration: OCI image export/import
• Boot Management: Automatic bootloader integration
• Transaction Safety: Rollback support for failed operations
• Comprehensive Logging: Detailed logging and monitoring

Development Status

The Ubuntu uBlue system is production-ready with:

• ✅ Core layer management (apt-layer.sh)
• ✅ Bootloader integration (bootloader-integration.sh)
• ✅ Immutable filesystem (composefs-alternative.sh)
• ✅ OCI integration (oci-integration.sh)
• ✅ Unified configuration (ublue-config.sh)
• ✅ Log management (ublue-logrotate.sh)
• ✅ Installation automation (install-ubuntu-ublue.sh)
• 🔄 Container-native booting (bootc-alternative.sh) - in development

Getting Help

• User Guides: Start with the README files in each component directory
• Quick References: Use the quickref files for common commands
• Troubleshooting: Check the troubleshooting guides for common issues
• API Reference: Use the API documentation for integration details

Contributing

The Ubuntu uBlue system is designed to be modular and extensible. Each component can be developed and improved independently while maintaining integration with the overall system.

For development guidelines and contribution information, see the individual component documentation.