Update md files (again)
This commit is contained in:
parent
6de5e1348b
commit
f76eebbc83
1 changed files with 482 additions and 0 deletions
482
Readme.md
482
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.
|
||||
Loading…
Add table
Add a link
Reference in a new issue