robojerk/particle-os-tools
1
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions

Initial commit: Particle-OS tools repository

Browse source 
- 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
This commit is contained in:
robojerk 2025-07-11 21:14:33 -07:00
commit 74c7bede5f
125 changed files with 66318 additions and 0 deletions
Download patch file Download diff file Expand all files Collapse all files

151
docs/README.md Normal file
View file

@ -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.

95
docs/bootc/README.md Normal file
View file

@ -0,0 +1,95 @@
# BootC Documentation
## Overview
BootC is a container-native bootable image system that provides an alternative approach to immutable system management. It allows running container images as bootable systems, providing a bridge between container technology and traditional system booting.
## BootC Alternative Script
The `bootc-alternative.sh` script provides:
- **Container Boot Support**: Boot from container images
- **Image Management**: Manage bootable container images
- **System Integration**: Integrate container images with bootloader
- **Update Management**: Handle container image updates
- **Status Information**: Get system status and image information
## Key Features
- **Container Native**: Uses standard container images as bootable systems
- **Immutable Design**: Container images are immutable and atomic
- **Update Management**: Atomic updates with rollback support
- **Boot Integration**: Seamless integration with standard bootloaders
- **OCI Compatibility**: Works with standard OCI container images
## Documentation Files
### Core Documentation
- **[bootc-guide.md](bootc-guide.md)** - Comprehensive user guide
- **[bootc-api.md](bootc-api.md)** - API reference and command documentation
- **[bootc-architecture.md](bootc-architecture.md)** - Technical architecture details
### Technical Documentation
- **[bootc-performance.md](bootc-performance.md)** - Performance considerations and optimization
- **[bootc-troubleshooting.md](bootc-troubleshooting.md)** - Common issues and solutions
- **[bootc-migration.md](bootc-migration.md)** - Migration from other boot systems
## Quick Start
```bash
# Install a container image as bootable system
bootc-alternative.sh install my-container:latest
# List installed bootable images
bootc-alternative.sh list
# Update to a new container image
bootc-alternative.sh update my-container:v2.0
# Rollback to previous image
bootc-alternative.sh rollback
# Get system status
bootc-alternative.sh status
```
## Integration
BootC integrates with:
- **apt-layer.sh**: For layer management within container images
- **bootloader-integration.sh**: For boot entry management
- **oci-integration.sh**: For OCI image handling
- **ublue-config.sh**: For unified configuration
## Architecture
BootC provides:
- **Container Boot**: Boot directly from container images
- **Immutable Updates**: Atomic updates with rollback support
- **Layer Management**: Support for layered container images
- **Boot Integration**: Standard bootloader compatibility
- **Update Management**: Automated update and rollback
## Performance Characteristics
- **Boot Performance**: Fast boot times from optimized container images
- **Update Performance**: Efficient delta updates between container layers
- **Storage Efficiency**: Layer deduplication and compression
- **Memory Usage**: Optimized memory usage for container boot
## Security Features
- **Immutable Images**: Container images cannot be modified at runtime
- **Atomic Updates**: All-or-nothing update semantics
- **Rollback Support**: Easy rollback to previous images
- **Integrity Verification**: Optional integrity checking
## Development Status
BootC is in development with:
- 🔄 Container boot support (in progress)
- 🔄 Image management (in progress)
- 🔄 Boot integration (planned)
- 🔄 Update management (planned)
- 🔄 Security features (planned)
For more information, see the individual documentation files listed above.

82
docs/bootupd/README.md Normal file
View file

@ -0,0 +1,82 @@
# bootloader-integration.sh Documentation
## Overview
`bootloader-integration.sh` provides integration between Ubuntu uBlue layer management and bootloader configuration. It bridges the gap between ComposeFS images and boot entries, ensuring that new layers are properly registered and can be booted.
## Script Description
The `bootloader-integration.sh` script enables:
- **Boot Entry Registration**: Register ComposeFS images with the bootloader
- **Default Boot Setting**: Set specific images as the default boot entry
- **Boot Entry Management**: Remove and list boot entries
- **Initramfs Updates**: Update initramfs for specific images
- **Integration with apt-layer.sh**: Automatic bootloader updates during layer operations
## Key Features
- **ComposeFS Integration**: Works with ComposeFS images and their paths
- **Bootupd Integration**: Uses bootupd-alternative.sh for boot entry management
- **Automatic Registration**: Integrates with apt-layer.sh for seamless operation
- **Kernel Version Detection**: Automatically detects and uses appropriate kernel versions
- **Initramfs Management**: Updates initramfs for new images
## Documentation Files
### Core Documentation
- **[bootloader-integration-guide.md](bootloader-integration-guide.md)** - Comprehensive user guide
- **[bootloader-integration-api.md](bootloader-integration-api.md)** - API reference and integration details
### Technical Documentation
- **[bootloader-security.md](bootloader-security.md)** - Security considerations and best practices
- **[bootloader-troubleshooting.md](bootloader-troubleshooting.md)** - Common issues and solutions
## Quick Start
```bash
# Register a new image with the bootloader
bootloader-integration.sh register ubuntu-ublue/gaming/24.04
# Set an image as the default boot entry
bootloader-integration.sh set-default ubuntu-ublue/gaming/24.04
# List all boot entries
bootloader-integration.sh list
# Update initramfs for an image
bootloader-integration.sh update-initramfs ubuntu-ublue/gaming/24.04
```
## Integration
`bootloader-integration.sh` integrates with:
- **apt-layer.sh**: Automatic bootloader updates during layer creation
- **composefs-alternative.sh**: For image path and status information
- **bootupd-alternative.sh**: For actual boot entry management
- **ublue-config.sh**: For unified configuration
## Architecture
The script provides:
- **Image Registration**: Maps ComposeFS images to boot entries
- **Boot Entry Management**: Creates, updates, and removes boot entries
- **Initramfs Updates**: Ensures boot images have current initramfs
- **Integration API**: Clean interface for other scripts to use
## Security Considerations
- **Path Validation**: Validates image paths before registration
- **Kernel Version Verification**: Ensures kernel version compatibility
- **Privilege Requirements**: Requires root privileges for bootloader operations
- **Error Handling**: Comprehensive error handling and rollback support
## Development Status
The script is production-ready with:
- ✅ Secure command execution (no eval usage)
- ✅ Comprehensive error handling
- ✅ Integration with apt-layer.sh
- ✅ Boot entry management
- ✅ Initramfs update support
For more information, see the individual documentation files listed above.

96
docs/composefs/README.md Normal file
View file

@ -0,0 +1,96 @@
# ComposeFS Documentation
## Overview
ComposeFS is the immutable filesystem backend for Ubuntu uBlue systems. It provides the foundation for atomic, layered system updates similar to OSTree but using squashfs and overlayfs technologies.
## ComposeFS Alternative Script
The `composefs-alternative.sh` script provides:
- **Image Creation**: Create ComposeFS images from directories
- **Image Mounting**: Mount ComposeFS images for access
- **Image Management**: List, remove, and manage ComposeFS images
- **Status Information**: Get system status and image information
- **Integration API**: Clean interface for other scripts
## Key Features
- **Immutable Images**: Squashfs-based immutable filesystem images
- **Layer Support**: Multiple layers can be combined using overlayfs
- **Atomic Operations**: All operations are atomic and recoverable
- **Efficient Storage**: Deduplication and compression for space efficiency
- **Boot Integration**: Seamless integration with bootloader systems
## Documentation Files
### Core Documentation
- **[composefs-guide.md](composefs-guide.md)** - Comprehensive user guide
- **[composefs-api.md](composefs-api.md)** - API reference and command documentation
- **[composefs-architecture.md](composefs-architecture.md)** - Technical architecture details
### Technical Documentation
- **[composefs-performance.md](composefs-performance.md)** - Performance considerations and optimization
- **[composefs-troubleshooting.md](composefs-troubleshooting.md)** - Common issues and solutions
- **[composefs-migration.md](composefs-migration.md)** - Migration from other filesystem technologies
## Quick Start
```bash
# Create a ComposeFS image
composefs-alternative.sh create my-image /path/to/source
# Mount a ComposeFS image
composefs-alternative.sh mount my-image /mnt/image
# List all images
composefs-alternative.sh list-images
# Get image information
composefs-alternative.sh info my-image
# Remove an image
composefs-alternative.sh remove my-image
```
## Integration
ComposeFS integrates with:
- **apt-layer.sh**: For layer creation and management
- **bootloader-integration.sh**: For boot image registration
- **oci-integration.sh**: For OCI image conversion
- **ublue-config.sh**: For unified configuration
## Architecture
ComposeFS provides:
- **Squashfs Images**: Compressed, immutable filesystem images
- **Overlayfs Layers**: Multiple layers combined for final filesystem
- **Atomic Operations**: All operations are atomic and recoverable
- **Efficient Storage**: Deduplication and compression
- **Boot Compatibility**: Compatible with standard bootloader systems
## Performance Characteristics
- **Read Performance**: Excellent read performance due to compression
- **Write Performance**: Immutable by design, changes create new layers
- **Storage Efficiency**: High compression ratios and deduplication
- **Boot Performance**: Fast boot times with optimized images
## Security Features
- **Immutable Images**: Cannot be modified once created
- **Integrity Verification**: Optional integrity checking
- **Atomic Updates**: All-or-nothing update semantics
- **Rollback Support**: Easy rollback to previous images
## Development Status
ComposeFS is production-ready with:
- ✅ Immutable filesystem support
- ✅ Layer management
- ✅ Atomic operations
- ✅ Boot integration
- ✅ Performance optimization
- ✅ Security features
For more information, see the individual documentation files listed above.