Initial commit: Particle-OS tools repository

- Complete Particle-OS rebranding from uBlue-OS - Professional installation system with standardized paths - Self-initialization system with --init and --reset commands - Enhanced error messages and dependency checking - Comprehensive testing infrastructure - All source scriptlets updated with runtime improvements - Clean codebase with redundant files moved to archive - Complete documentation suite
2025-07-11 21:14:33 -07:00 · 2025-07-11 21:14:33 -07:00 · 74c7bede5f
commit 74c7bede5f
125 changed files with 66318 additions and 0 deletions
--- a/docs/README.md
+++ b/docs/README.md
@ -0,0 +1,151 @@
+# 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](../ubuntu_tools/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/](apt-layer/)
+
+#### [bootloader-integration.sh](../ubuntu_tools/bootloader-integration.sh)
+Provides integration between layer management and bootloader configuration, ensuring new layers are properly registered and bootable.
+
+**Documentation**: [bootupd/](bootupd/)
+
+#### [composefs-alternative.sh](../ubuntu_tools/composefs-alternative.sh)
+The immutable filesystem backend for Ubuntu uBlue systems, providing atomic, layered system updates using squashfs and overlayfs.
+
+**Documentation**: [composefs/](composefs/)
+
+#### [bootc-alternative.sh](../ubuntu_tools/bootc-alternative.sh)
+Container-native bootable image system that allows running container images as bootable systems.
+
+**Documentation**: [bootc/](bootc/)
+
+### Supporting Scripts
+
+#### [oci-integration.sh](../ubuntu_tools/oci-integration.sh)
+Provides OCI export/import functionality for ComposeFS images, enabling container registry integration.
+
+#### [ublue-config.sh](../ubuntu_tools/ublue-config.sh)
+Unified configuration system providing consistent paths, logging, and settings across all Ubuntu uBlue scripts.
+
+#### [ublue-logrotate.sh](../ubuntu_tools/ublue-logrotate.sh)
+Log rotation utility for Ubuntu uBlue logs with configurable patterns and compression.
+
+#### [install-ubuntu-ublue.sh](../ubuntu_tools/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
+```bash
+# Install the complete Ubuntu uBlue system
+sudo ./ubuntu_tools/install-ubuntu-ublue.sh
+```
+
+### Basic Usage
+```bash
+# 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.