# Ubuntu uBlue System Tools

A comprehensive collection of tools for creating and managing immutable Ubuntu systems, providing functionality similar to Fedora Silverblue/Kinoite but designed specifically for Ubuntu/Debian-based distributions.

## 🎯 Overview

Ubuntu uBlue System Tools provides a complete solution for immutable Ubuntu systems using:
- **ComposeFS Alternative**: Immutable filesystem backend using squashfs and overlayfs
- **apt-layer**: Package management and layer creation (similar to rpm-ostree)
- **bootupd Alternative**: Bootloader management and deployment
- **Live Overlay System**: Temporary package installation without rebooting
- **OCI Integration**: Container image export/import capabilities
- **Transaction Management**: Atomic operations with rollback support
- **fsverity**: File integrity verification and signing

## 🏗️ System Architecture

```
┌─────────────────────────────────────────────────────────────┐
│                    Ubuntu uBlue System                      │
├─────────────────────────────────────────────────────────────┤
│  main.sh (Orchestrator)                                     │
│  ┌─────────────┬─────────────┬─────────────┐                │
│  │ apt-layer.sh│composefs-alt│bootupd-alt  │                │
│  │             │             │             │                │
│  │ • Package   │ • Immutable │ • Bootloader│                │
│  │   layers    │   filesystem│   management│                │
│  │ • Live      │ • SquashFS  │ • UEFI/GRUB │                │
│  │   overlay   │ • OverlayFS │ • Deployment│                │
│  └─────────────┴─────────────┴─────────────┘                │
├─────────────────────────────────────────────────────────────┤
│  Supporting Tools                                           │
│  • oci-integration.sh    • ublue-config.sh                 │
│  • bootc-alternative.sh  • ublue-logrotate.sh              │
│  • dracut-module.sh      • install-ubuntu-ublue.sh         │
│  • fsverity-utils        • Integrity verification          │
└─────────────────────────────────────────────────────────────┘
```

## 🚀 Quick Start

### Installation

```bash
# Clone the repository
git clone <repository-url>
cd tools

# Run the installation script
sudo ./install-ubuntu-ublue.sh

# Verify installation
sudo ./test-integration.sh
```

### Basic Usage

```bash
# Install packages and create new system image
sudo ./main.sh install ubuntu-base-24.04 firefox steam

# Install packages on live system (no reboot required)
sudo ./apt-layer.sh --live-install firefox steam

# Commit live changes to permanent layer
sudo ./apt-layer.sh --live-commit "Add gaming packages"

# Rebase to new Ubuntu version
sudo ./main.sh rebase ubuntu-base-25.04

# Rollback to previous deployment
sudo ./main.sh rollback

# Check system status
sudo ./main.sh status
```

## 📦 Core Components

### 1. **main.sh** - System Orchestrator
The central orchestrator that coordinates all uBlue operations:
- **Package Installation**: Atomic package installation with new image creation
- **System Rebase**: Upgrade to new base images while preserving layers
- **Rollback Management**: Safe rollback to previous deployments
- **Transaction Management**: Atomic operations with automatic rollback

**Usage:**
```bash
sudo ./main.sh install <base-image> <package1> [package2]...
sudo ./main.sh rebase <new-base-image>
sudo ./main.sh rollback [target-image]
sudo ./main.sh status
```

### 2. **apt-layer.sh** - Package Layer Management
Advanced package management with layer-based approach:
- **Layer Creation**: Create new system layers with packages
- **Live Overlay**: Install packages without rebooting
- **Container Support**: Build layers in containers for isolation
- **Transaction Safety**: Atomic layer operations with rollback
- **OCI Integration**: Export/import layers as container images

**Usage:**
```bash
# Create new layer (traditional chroot-based)
sudo ./apt-layer.sh ubuntu-base/24.04 gaming/24.04 steam wine

# Create layer with container isolation
sudo ./apt-layer.sh --container ubuntu-base/24.04 dev/24.04 vscode git

# Live package installation (no reboot required)
sudo ./apt-layer.sh --live-install firefox

# Commit live changes to permanent layer
sudo ./apt-layer.sh --live-commit "Add browser"

# Export layer as OCI container image
sudo ./apt-layer.sh --oci-export gaming/24.04 my-registry/gaming:latest

# List all layers
sudo ./apt-layer.sh --list

# Rollback to previous layer
sudo ./apt-layer.sh --rollback gaming/24.04
```

### 3. **composefs-alternative.sh** - Immutable Filesystem
Provides immutable filesystem functionality using squashfs and overlayfs:
- **Image Creation**: Create compressed system images
- **Layer Management**: Manage multiple filesystem layers
- **Mount Management**: Mount/unmount images with overlay support
- **Content Verification**: Hash-based content verification

**Usage:**
```bash
# Create image from directory
sudo ./composefs-alternative.sh create my-image /path/to/rootfs

# Mount image
sudo ./composefs-alternative.sh mount my-image /mnt/point

# List images
sudo ./composefs-alternative.sh list-images

# Remove image
sudo ./composefs-alternative.sh remove my-image
```

### 4. **bootupd-alternative.sh** - Bootloader Management
Manages bootloader configuration and deployment:
- **UEFI Support**: Full UEFI bootloader management
- **GRUB Integration**: GRUB configuration and updates
- **Deployment**: Deploy new images as bootable entries
- **Rollback**: Safe bootloader rollback capabilities
- **Multi-bootloader Support**: UEFI, GRUB, LILO, syslinux

**Usage:**
```bash
# Set default boot entry
sudo ./bootupd-alternative.sh set-default my-image

# List boot entries
sudo ./bootupd-alternative.sh list-entries

# Check status
sudo ./bootupd-alternative.sh status

# Rollback bootloader
sudo ./bootupd-alternative.sh rollback

# Register new image with bootloader
sudo ./bootupd-alternative.sh register my-image
```

## 🔧 Supporting Tools

### **oci-integration.sh**
OCI container image export/import for ComposeFS images:
```bash
# Export layer as OCI image
sudo ./oci-integration.sh export my-layer my-registry/my-image:latest

# Import OCI image as layer
sudo ./oci-integration.sh import my-registry/my-image:latest my-layer

# List available OCI images
sudo ./oci-integration.sh list
```

### **bootc-alternative.sh**
Container-native bootable image system:
```bash
# Create bootable container image
sudo ./bootc-alternative.sh create ubuntu:24.04 my-bootable-image

# Deploy container as bootable system
sudo ./bootc-alternative.sh deploy my-bootable-image

# Update to new container image
sudo ./bootc-alternative.sh update my-container:v2.0

# Rollback to previous image
sudo ./bootc-alternative.sh rollback
```

### **ublue-config.sh**
Unified configuration system:
```bash
# Show configuration
sudo ./ublue-config.sh show

# Update configuration
sudo ./ublue-config.sh update

# Validate configuration
sudo ./ublue-config.sh validate
```

### **ublue-logrotate.sh**
Log rotation and maintenance:
```bash
# Rotate oversized logs
sudo ./ublue-logrotate.sh rotate

# Clean up old logs
sudo ./ublue-logrotate.sh cleanup

# Show log statistics
sudo ./ublue-logrotate.sh stats
```

## 🧪 Testing

Comprehensive test suite for all components:

```bash
# Run full integration tests
sudo ./test-integration.sh

# Test specific components
sudo ./test-apt-layer.sh
sudo ./test-composefs-integration.sh
```

## 📋 Requirements

### System Requirements
- **OS**: Ubuntu 22.04+ / Debian 12+ / Pop!_OS 22.04+
- **Architecture**: x86_64, ARM64
- **Boot**: UEFI or Legacy BIOS
- **Storage**: 20GB+ free space
- **Memory**: 4GB+ RAM

### Dependencies
```bash
# Core dependencies
sudo apt install squashfs-tools jq rsync mount losetup

# Bootloader dependencies
sudo apt install grub-efi-amd64 efibootmgr

# File integrity verification
sudo apt install fsverity-utils

# Container dependencies (optional)
sudo apt install podman docker.io
```

## 🔒 Security Features

- **Immutable Design**: System images cannot be modified at runtime
- **Content Verification**: SHA256 hash verification of all content
- **Transaction Safety**: Atomic operations with automatic rollback
- **Isolation**: Container-based layer building for security
- **Audit Logging**: Comprehensive logging of all operations
- **Command Injection Protection**: Safe command execution without eval
- **Resource Cleanup**: Automatic cleanup of temporary files and mounts
- **Path Validation**: Input sanitization and path traversal protection

## 📚 Documentation

Detailed documentation is available in the `docs/` directory:

- **[apt-layer/](docs/apt-layer/)**: Complete apt-layer.sh documentation
- **[composefs/](docs/composefs/)**: ComposeFS alternative documentation  
- **[bootupd/](docs/bootupd/)**: Bootloader management documentation
- **[bootc/](docs/bootc/)**: Container-native booting documentation

## 🚧 Development Status

| Component | Status | Notes |
|-----------|--------|-------|
| apt-layer.sh | ✅ Production Ready | Full layer management with live overlay, OCI integration |
| composefs-alternative.sh | ✅ Production Ready | Immutable filesystem backend with squashfs/overlayfs |
| bootupd-alternative.sh | ✅ Production Ready | Multi-bootloader support (UEFI, GRUB, LILO, syslinux) |
| main.sh | ✅ Production Ready | System orchestrator with transaction management |
| oci-integration.sh | ✅ Production Ready | Container image export/import |
| ublue-config.sh | ✅ Production Ready | Unified configuration system |
| ublue-logrotate.sh | ✅ Production Ready | Log rotation and maintenance |
| bootc-alternative.sh | 🔄 In Development | Container-native booting |

## 🤝 Contributing

This project welcomes contributions! Please see the individual component documentation for development guidelines.

### Development Setup
```bash
# Clone repository
git clone <repository-url>
cd tools

# Install development dependencies
sudo ./install-ubuntu-ublue.sh --dev

# Run tests
sudo ./test-integration.sh

# Run component-specific tests
sudo ./test-apt-layer.sh
sudo ./test-composefs-integration.sh
```

### Development Guidelines
- Follow the existing code style and patterns
- Add comprehensive error handling and logging
- Include tests for new features
- Update documentation for any API changes
- Ensure all operations are atomic with rollback support

## 📄 License

This project is open source. Please check individual component licenses.

## 🆘 Support

- **Issues**: Report bugs and feature requests via GitHub issues
- **Documentation**: Check the `docs/` directory for detailed guides
- **Testing**: Run `./test-integration.sh` for system diagnostics
- **Troubleshooting**: Check component-specific troubleshooting guides in `docs/`
- **Security**: Review security analysis in `docs/apt-layer/AGGRESSIVE-SCRUTINY-RESPONSE.md`

---

**Note**: All tools are designed to work 1:1 with their official counterparts and are compatible with Ubuntu, Debian, and Pop!_OS systems.