particle-os-tools/Readme.md

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