bootc-deb/README.md

# Bootc Debian Package Builder

A complete solution for building and distributing bootc .deb packages for Debian/Ubuntu systems with libostree 2025.2-1 compatibility. This repository provides automated CI/CD workflows that build bootc packages and upload them to a Forgejo package repository.

## 🎯 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
- **CI/CD**: Automated build pipeline with package upload to Forgejo
- **Package Repository Integration**: Automatic upload to Forgejo package registry

**Note**: The libostree 2025.2-1 packages are available as Debian packages in the Forgejo repository: [libostree-dev](https://git.raines.xyz/particle-os/libostree-dev)

## 🚀 Quick Start

### Prerequisites

1. **Basic build tools**: `git`, `cargo`, `rustc`, `pkg-config`
2. **Ubuntu Noble (24.04 LTS)** system
3. **libostree 2025.2-1 packages** from Forgejo repository

### Complete Workflow

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

# Step 1: Install libostree 2025.2-1 packages from Forgejo
curl -fsSL https://git.raines.xyz/api/packages/particle-os/debian/repository.key | sudo gpg --dearmor -o /usr/share/keyrings/forgejo-particle-os.gpg
echo "deb [signed-by=/usr/share/keyrings/forgejo-particle-os.gpg] https://git.raines.xyz/api/packages/particle-os/debian trixie main" | sudo tee /etc/apt/sources.list.d/forgejo-particle-os.list
sudo apt update
sudo apt install -y libostree-dev=2025.2-1~trixie1 libostree-1-1=2025.2-1~trixie1

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

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

### Alternative: Test Installation

```bash
# Test that libostree packages can be installed
./test-libostree-install.sh
```

## 📁 Repository Structure

```
bootc-deb/
├── bootc-libostree-compatibility.patch    # The compatibility fix
├── build.sh                               # Build script (clones + builds)
├── install.sh                             # Installation script
├── test-libostree-install.sh             # Test libostree package installation
├── test-debian-upload.sh                 # Test package upload functionality
├── libostree-dev_trixie_backport.sh        # Legacy backport script (see separate repo)
├── README.md                              # This file
├── .forgejo/                              # CI/CD workflows
│   ├── workflows/
│   │   ├── build-packages.yml             # Full build pipeline with package upload
│   │   ├── test-build.yml                 # Test workflow
│   │   └── update-readme.yml              # README update workflow
└── debian/                                # Debian packaging files
    ├── control                            # Package metadata
    ├── rules                              # Build rules
    ├── changelog                          # Version history
    └── copyright                          # License info
```

## 🔧 How It Works

### The Complete Process

1. **Installs libostree 2025.2-1** from Forgejo package repository
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. **Uploads packages** to Forgejo package registry
7. **Creates release assets** for manual download

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

# Install from Forgejo package repository
curl -fsSL https://git.raines.xyz/api/packages/particle-os/debian/repository.key | sudo gpg --dearmor -o /usr/share/keyrings/forgejo-particle-os.gpg
echo "deb [signed-by=/usr/share/keyrings/forgejo-particle-os.gpg] https://git.raines.xyz/api/packages/particle-os/debian trixie main" | sudo tee /etc/apt/sources.list.d/forgejo-particle-os.list
sudo apt update
sudo apt install -y bootc
```

The complete workflow will:
- ✅ Install libostree 2025.2-1 from Forgejo repository
- ✅ Install bootc from Forgejo repository
- ✅ All dependencies handled automatically

## 📦 Package Information

- **Package Name**: bootc
- **Version**: 1.5.1-1~trixie1
- **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 (available in Forgejo repository)

### Package Repository Integration

Both libostree and bootc packages are available from the Forgejo package repository:

- **Repository**: [libostree-dev](https://git.raines.xyz/particle-os/libostree-dev)
- **Package Registry**: [Forgejo Packages](https://git.raines.xyz/particle-os/-/packages)
- **Automated builds** with CI/CD integration
- **Complete dependency chain** from libostree to bootc
- **Easy installation** via standard apt commands

## 🛠️ Manual Steps (if needed)

If you prefer to build manually:

```bash
# 1. Install libostree 2025.2-1 backport (if needed)
# See: https://git.raines.xyz/particle-os/libostree-dev

# 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.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.sh`
3. Update documentation if needed

### CI/CD Automation

This repository includes Forgejo Actions workflows for automated package building and distribution:

- **`.forgejo/workflows/build-packages.yml`**: Full build pipeline with package upload to Forgejo
- **`.forgejo/workflows/test-build.yml`**: Lightweight testing for development and PRs
- **`.forgejo/workflows/update-readme.yml`**: README update workflow

#### Automated Build Process

1. **Triggers**: Push to main/master, pull requests, and releases
2. **Dependencies**: Installs libostree 2025.2-1 from Forgejo repository
3. **Build**: Builds bootc with libostree compatibility patch
4. **Upload**: Automatically uploads packages to Forgejo package registry
5. **Release Assets**: Creates downloadable artifacts for manual installation

#### Package Repository Integration

- **Automatic Upload**: Packages are uploaded to Forgejo after successful builds
- **Repository Association**: Packages are automatically associated with the repository
- **Dependency Resolution**: Users can install directly via apt with proper dependencies
- **Version Management**: Each build creates a new package version

#### Manual Workflow Triggers

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

## 🎉 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**: Install from Forgejo repository using the commands in Quick Start
- **Build dependencies**: The workflow installs them automatically
- **Git clone issues**: Check internet connection
- **Package upload failures**: Verify FORGEJO_TOKEN secret is set correctly

### Runtime Issues
- **Missing runtime dependencies**: Run `sudo apt-get install -f`
- **AppArmor denials**: Monitor with `sudo aa-logprof`
- **Package installation issues**: Ensure Forgejo repository is properly configured

### Testing

Use the provided test scripts to verify functionality:

```bash
# Test libostree package installation
./test-libostree-install.sh

# Test package upload functionality
./test-debian-upload.sh
```

---

**Perfect for distributing bootc as .deb packages on any Ubuntu Noble system with automated CI/CD!** 🎉