robojerk
74c7bede5f
- 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
151 lines
No EOL
6.4 KiB
Markdown
151 lines
No EOL
6.4 KiB
Markdown
# 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. |