bootc-deb/README.md

# Bootc Debian Package Builder

A minimal repository containing the patch and deb packaging tooling to build bootc .deb packages for Debian/Ubuntu systems with libostree 2025.2-1 compatibility.

## 🎯 What This Repository Contains

- **Patch**: Fixes compatibility with libostree 2025.2-1 on Ubuntu Noble
- **Debian Packaging**: Complete debian/ directory structure
- **Build Script**: Automatically clones bootc source and builds .deb
- **Install Script**: Installs the built package with dependency handling
- **Dependency Backport**: Automated script to backport libostree 2025.2-1 from Ubuntu Questing

## 🚀 Quick Start

### Prerequisites

1. **Basic build tools**: `git`, `cargo`, `rustc`, `pkg-config`
2. **Ubuntu Noble (24.04 LTS)** system

### Complete Workflow

```bash
# Clone this repository
git clone <your-repo-url> bootc-deb
cd bootc-deb

# Step 1: Backport libostree 2025.2-1 (if not already installed)
./libostree-dev_noble_backport.sh

# Step 2: Build the bootc .deb package
./build-bootc-deb.sh

# Step 3: Install the package
sudo ./install-bootc.sh
```

## 📁 Repository Structure

```
bootc-deb/
├── bootc-libostree-compatibility.patch    # The compatibility fix
├── build-bootc-deb.sh                     # Build script (clones + builds)
├── install-bootc.sh                       # Installation script
├── libostree-dev_noble_backport.sh        # Dependency backport script
├── README.md                              # This file
├── PACKAGING_SUMMARY.md                   # Detailed summary
├── .forgejo/                              # CI/CD workflows
│   ├── workflows/
│   │   ├── build-packages.yml             # Full build pipeline
│   │   ├── test-build.yml                 # Test workflow
│   │   ├── update-readme.yml              # README update workflow
│   │   └── config.yml                     # CI/CD configuration
└── debian/                                # Debian packaging files
    ├── control                            # Package metadata
    ├── rules                              # Build rules
    ├── changelog                          # Version history
    └── copyright                          # License info
```

## 🔧 How It Works

### The Complete Process

1. **Backports libostree 2025.2-1** from Ubuntu Questing to Noble (if needed)
2. **Clones bootc source** from GitHub (v1.5.1)
3. **Applies our patch** to fix libostree compatibility
4. **Installs build dependencies** automatically
5. **Builds the .deb package** using dpkg-buildpackage
6. **Copies results** to the repository directory

### The Patch

Fixes this issue in `crates/lib/src/cli.rs`:

```rust
// Before (causes build failure):
ostree::SePolicy::set_null_log();

// After (compatible):
// TODO: Re-enable when ostree Rust bindings support set_null_log()
// ostree::SePolicy::set_null_log();
```

## 🌍 Usage on Any PC

This repository is designed to work on any Ubuntu Noble system:

```bash
# On any PC in the world:
git clone <your-repo-url> bootc-deb
cd bootc-deb
./libostree-dev_noble_backport.sh  # Step 1: Get required dependencies
./build-bootc-deb.sh               # Step 2: Build bootc package
sudo ./install-bootc.sh            # Step 3: Install the package
```

The complete workflow will:
- ✅ Backport libostree 2025.2-1 from Ubuntu Questing
- ✅ Clone bootc source from GitHub
- ✅ Apply the compatibility patch
- ✅ Install all build dependencies
- ✅ Build the .deb package
- ✅ Install the package

## 📦 Package Information

- **Package Name**: bootc
- **Version**: 1.5.1-1~noble1
- **Target**: Ubuntu Noble (24.04 LTS)
- **Dependencies**: libostree-1-1 (>= 2025.2), systemd, podman|docker.io, skopeo

## 🔗 Integration with apt-ostree

This packaging is specifically designed for Aurora-style workflow:

1. **OCI Image Compatibility**: Works with apt-ostree generated images
2. **Container Tool Integration**: Compatible with podman, skopeo
3. **System Integration**: Proper Ubuntu Noble integration
4. **Version Compatibility**: Requires libostree 2025.2-1 (automated backport included)

### Dependency Management
The `libostree-dev_noble_backport.sh` script provides:
- **Automated backporting** of libostree 2025.2-1 from Ubuntu Questing
- **Safety features** including VM detection and disk space checks
- **Complete build process** with proper Debian packaging
- **Seamless integration** with the bootc packaging workflow

## 🛠️ Manual Steps (if needed)

If you prefer to build manually:

```bash
# 1. Backport libostree 2025.2-1 (if needed)
./libostree-dev_noble_backport.sh

# 2. Clone bootc source
git clone --depth 1 --branch v1.5.1 https://github.com/containers/bootc.git bootc-1.5.1
cd bootc-1.5.1

# 3. Apply patch
patch -p1 < ../bootc-libostree-compatibility.patch

# 4. Copy packaging files
cp -r ../debian .

# 5. Build package
dpkg-buildpackage -us -uc -b
```

## 🔄 Maintenance

### Updating Versions

1. Update version in `debian/changelog`
2. Update version in `build-bootc-deb.sh`
3. Update version in `.forgejo/workflows/build-packages.yml`
4. Test build process

### Updating the Patch

1. Modify `bootc-libostree-compatibility.patch`
2. Test with `./build-bootc-deb.sh`
3. Update documentation if needed

### CI/CD Automation

This repository includes Forgejo Actions workflows for automated package building:

- **`.forgejo/workflows/build-packages.yml`**: Full build pipeline for both libostree backport and bootc
- **`.forgejo/workflows/test-build.yml`**: Lightweight testing for development and PRs
- **`.forgejo/workflows/config.yml`**: CI/CD configuration settings

#### Automated Build Process

1. **Triggers**: Push to main/master, pull requests, and releases
2. **libostree Backport**: Automatically builds libostree 2025.2-1 from Ubuntu Questing
3. **bootc Package**: Builds bootc with the backported libostree dependency
4. **Artifacts**: Uploads .deb packages as build artifacts
5. **Releases**: Creates release assets when a new release is published

#### Manual Workflow Triggers

You can manually trigger builds in the Forgejo Actions tab:
- **Test Build**: Quick validation of bootc build process
- **Full Build**: Complete libostree backport + bootc package build

#### Automatic README Updates

The CI/CD automatically updates the README with download links to the latest packages:
- **Trigger**: After successful package builds
- **Content**: Direct download links to .deb files
- **Instructions**: Installation commands for users
- **Timestamp**: Shows when packages were last built

## 🎉 Success!

After installation, you'll have:

- ✅ **bootc command** available system-wide
- ✅ **Full functionality** with your apt-ostree OCI images
- ✅ **Aurora-style workflow** ready to use

## 📋 Troubleshooting

### Build Issues
- **Missing libostree 2025.2-1**: Run `./libostree-dev_noble_backport.sh` first
- **Build dependencies**: The script installs them automatically
- **Git clone issues**: Check internet connection
- **Backport build failures**: Ensure you have sufficient disk space (500MB+) and are in a VM for safety

### Runtime Issues
- **Missing runtime dependencies**: Run `sudo apt-get install -f`
- **AppArmor denials**: Monitor with `sudo aa-logprof`

---

**Perfect for distributing bootc as .deb packages on any Ubuntu Noble system!** 🎉