From f76eebbc83353391cf3515273ed063c5a75475f4 Mon Sep 17 00:00:00 2001 From: robojerk Date: Mon, 14 Jul 2025 08:09:28 -0700 Subject: [PATCH] Update md files (again) --- Readme.md | 482 ++++++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 482 insertions(+) diff --git a/Readme.md b/Readme.md index e69de29..69cba7f 100644 --- a/Readme.md +++ b/Readme.md @@ -0,0 +1,482 @@ +# 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:** +```bash +# 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:** +```bash +# 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:** +```bash +# 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:** +```bash +# 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:** +```bash +# 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:** +```bash +# 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:** +```bash +# 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** +```bash +# 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** +```bash +# 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** +```bash +# Initialize Particle-OS system +sudo apt-layer.sh --init + +# Configure bootloader +sudo bootupd-alternative.sh init +``` + +### **2. Package Management** +```bash +# 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** +```bash +# 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** +```bash +# 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`: + +```bash +# 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: + +```bash +# 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: + +```bash +# 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** +```bash +# 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** +```bash +# Test complete workflow +sudo ./test-complete-workflow.sh + +# Test rollback scenarios +sudo ./test-rollback-scenarios.sh +``` + +## Troubleshooting + +### **Common Issues** + +1. **DNS Resolution in WSL** + ```bash + # 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** + ```bash + # Reinstall bootloader + sudo bootupd-alternative.sh reinstall + ``` + +3. **Layer Mounting Problems** + ```bash + # Check layer integrity + sudo composefs-alternative.sh verify layer-name + ``` + +### **Log Files** +```bash +# 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](docs/INSTALLATION.md) +- [Troubleshooting Guide](docs/TROUBLESHOOTING_GUIDE.md) +- [API Documentation](docs/API.md) + +### **Community** +- GitHub Issues: [Report bugs and request features](https://github.com/your-org/particle-os-tools/issues) +- Discussions: [Community discussions](https://github.com/your-org/particle-os-tools/discussions) + +### **Development** +- Contributing Guide: [How to contribute](CONTRIBUTING.md) +- Development Setup: [Development environment](docs/DEVELOPMENT.md) + +## Roadmap + +### **Phase 1: Core Stability** +- [x] Modular architecture implementation +- [x] Transaction management system +- [x] Traditional layer creation +- [x] ComposeFS backend integration + +### **Phase 2: Enhanced Features** +- [x] Container-based layer creation +- [x] OCI integration +- [x] Live system layering + +### **Phase 3: Bootloader Integration** +- [x] Multi-bootloader support +- [x] Kernel arguments management +- [x] Boot entry management +- [x] Atomic deployment integration + +### **Phase 4: OSTree Atomic Package Management** +- [x] OSTree atomic commits for package operations +- [x] Atomic deployment with rollback capabilities +- [x] Versioned package history +- [x] 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. \ No newline at end of file