bootc-docs/COMPATIBILITY.md

# Compatibility Matrix

This document provides compatibility information for bootc on Debian systems.

## Verified Compatibility Matrix

| Component | Minimum Version | Tested Version | Notes |
|-----------|----------------|----------------|-------|
| **bootc** | v1.1.4 | v1.1.4 | Main branch, composefs-backend experimental |
| **Debian Base** | Sid (unstable) | Sid | Recommended for base image building |
| **Debian Base** | 14 (Forky) | 14 (Forky) | Ideal (testing, latest OSTree) |
| **Debian Base** | 13 (Trixie) | 13 (Trixie) | Stable, may need OSTree backports |
| **Debian Base** | 12 (Bookworm) | ❌ | Not supported (OSTree too old) |
| **Kernel** | 6.1 | 6.5+ | Minimum 6.1, 6.5+ for composefs features |
| **Podman** | 4.0 | 4.0+ | Required for container operations |
| **OSTree** | 2024.1 | 2024.3+ | Required for deployments |
| **composefs** | N/A | Experimental | Requires kernel 6.5+ for full features |

## Feature Compatibility by bootc Version

| Feature | bootc Version | Kernel Requirement | Notes |
|---------|---------------|-------------------|-------|
| Basic install | v1.1.4+ | 6.1+ | Manual installation recommended |
| Composefs backend | v1.1.4+ | 6.5+ | Experimental, requires feature flag |
| `--progress-fd` | v1.1.4+ | Any | Experimental flag |
| `--no-signature-verification` | v1.1.4+ | Any | Bypasses security checks |
| `--mutate-in-place` | v1.1.4+ | Any | In-place mutations |
| `--json` output | v1.1.4+ | Any | JSON format output |

## Feature Compatibility

### Core Features
- ✅ `bootc install` - Manual installation recommended
- ✅ `bootc upgrade` - Works with proper setup
- ✅ `bootc status` - Full functionality
- ✅ `bootc switch` - Image switching supported
- ✅ `bootc rollback` - Rollback functionality
- ✅ `bootc usr-overlay` - Temporary /usr modifications

### Hidden/Internal Features
- ✅ `bootc image` - Image management
- ✅ `bootc internals` - Internal operations
- ✅ `bootc state` - State management
- ⚠️ `bootc exec-in-host-mount-namespace` - Requires privileged access
- ⚠️ `bootc composefs-finalize-staged` - Composefs backend only

### Experimental Features
- ⚠️ `--progress-fd` - Available since bootc v1.1.4
- ⚠️ `--no-signature-verification` - Bypasses security checks
- ⚠️ `--mutate-in-place` - In-place mutations
- ⚠️ `--json` - JSON output format
- ⚠️ `--target-no-signature-verification` - Target signature bypass

## Kernel Requirements Checklist

### Basic bootc Requirements (Kernel 6.1+)
- ✅ **OSTree support**: Basic OSTree operations
- ✅ **Container runtime**: Podman/containerd support
- ✅ **systemd**: Full systemd integration
- ✅ **AppArmor**: Security labeling (Debian default)

### Composefs Backend Requirements (Kernel 6.5+)
- ✅ **EROFS**: Enhanced Read-Only File System support
- ✅ **composefs**: Kernel composefs module
- ✅ **overlayfs**: Overlay filesystem support
- ✅ **fsverity**: File system verification
- ⚠️ **Advanced verity**: Kernel 6.6+ for certain integrity modes

### Userspace Requirements
- **composefs tools**: Userspace composefs utilities
- **EROFS support**: Enhanced Read-Only File System support
- **fsverity**: File system verification support
- **FUSE3**: For fallback mounting (if kernel support unavailable)

### Kernel Feature Verification
```bash
# Check kernel version
uname -r

# Check for EROFS support
grep EROFS /proc/filesystems

# Check for composefs support
grep composefs /proc/filesystems

# Check for overlayfs support
grep overlay /proc/filesystems

# Check for fsverity support
grep fsverity /proc/filesystems
```

### Feature Flags
- `composefs-backend` - Enable composefs backend
- `install-to-disk` - Direct disk installation
- `rhsm` - Red Hat Subscription Manager (not applicable to Debian)

## Debian-Specific Considerations

### Package Availability
- **bootc**: Not packaged in Debian main (compile from source)
- **ostree**: Available in Debian repositories
- **podman**: Available in Debian repositories
- **composefs**: May require manual compilation

### Build Dependencies
```bash
# Required for bootc compilation
sudo apt install -y build-essential git pkg-config libostree-dev libglib2.0-dev libgpgme-dev libseccomp-dev cargo rustc

# Required for composefs backend
sudo apt install -y libfuse3-dev libfuse3-3
```

### Runtime Dependencies
```bash
# Required for bootc operation
sudo apt install -y ostree podman systemd
```

## Known Issues

### Critical: grub2-mkconfig Composefs Incompatibility

**⚠️ CRITICAL ISSUE**: `grub2-mkconfig` is incompatible with composefs and will cause boot failures.

**Problem**: 
- `grub2-mkconfig` doesn't know how to read `/sysroot` where the physical root filesystem lives
- This affects all bootc/ostree systems using composefs
- Reported in [Red Hat Bugzilla #2308594](https://bugzilla.redhat.com/show_bug.cgi?id=2308594)

**Solution**: Apply this patch to `/usr/sbin/grub2-mkconfig`:

```bash
# Add this code after line 138 in grub2-mkconfig
# Path to the real rootfs; we may be in a container or using bootc/ostree
GRUB_PHYSICAL_FILESYSTEM=/
GRUB_FS="$(stat -f -c %T / || echo unknown)"
if test "x${GRUB_FS}" = "xoverlay" && test -d /sysroot; then
  GRUB_PHYSICAL_FILESYSTEM=/sysroot
fi

# Then change this line:
# GRUB_DEVICE="`${grub_probe} --target=device /`"
# To:
GRUB_DEVICE="`${grub_probe} --target=device ${GRUB_PHYSICAL_FILESYSTEM}`"
```

**Workaround**: 
- Apply the patch before running `grub2-mkconfig`
- Or use alternative bootloader configuration methods
- This issue affects all composefs-based bootc images

### Debian-Specific Problems
1. **bootc install reliability**: May fail on Debian due to Fedora-centric development
2. **Missing dependencies**: Some bootc dependencies may not be available
3. **Compilation issues**: Rust dependencies may not compile cleanly
4. **Runtime errors**: Even if compiled, bootc may fail at runtime
5. **OSTree version issues**: Debian 12 (Bookworm) has outdated OSTree packages

### Workarounds
1. **Manual installation**: Use provided scripts to bypass bootc install
2. **Hybrid approach**: Manual install + bootc management
3. **Validation scripts**: Manual validation of bootc-compatible images
4. **Containerfile fixes**: Use symlinks instead of systemctl commands
5. **OSTree backporting**: Backport newer OSTree libraries from Forky to Trixie

## Testing Matrix

### Experimental Configurations
- ⚠️ Debian 13 (Trixie) + bootc v1.1.4 + Podman 4.0 (experimental, not fully tested), might need OSTree packages backported from Forky
- ⚠️ Debian 14 (Forky) + bootc v1.1.4 + Podman 4.0 (experimental, not fully tested)
- ⚠️ Debian 00 (sid)
- ⚠️ Debian 12 (Bookworm) + manual installation + bootc management (old OSTree, experimental)
- ⚠️ Debian 12 (Bookworm) + composefs backend (experimental, old OSTree)
- ❌ Debian 11 (Bullseye) - Not tested, may have issues
- ❌ **No reproducible bootc images exist yet** - All configurations are experimental

### Untested Configurations
- Other Debian derivatives (Ubuntu, etc.)

## OSTree Backporting Guide

### Backporting OSTree from Forky to Trixie

If you need newer OSTree libraries on Trixie, you can backport them from Forky:

```bash
# Add Forky sources temporarily
echo "deb http://deb.debian.org/debian testing main" | sudo tee /etc/apt/sources.list.d/forky.list

# Download newer OSTree packages
apt download ostree libostree-1-1 ostree-tests

# Install the newer packages
sudo dpkg -i ostree_*.deb libostree-1-1_*.deb

# Remove temporary sources
sudo rm /etc/apt/sources.list.d/forky.list
sudo apt update
```

### Benefits of Newer OSTree
- **bootupd support**: Required for bootloader management
- **Better bootc compatibility**: Newer APIs and features
- **Performance improvements**: Optimized deployment operations
- **Security updates**: Latest security patches

## Recommendations

### For Production Use
⚠️ **WARNING: bootc on Debian is EXPERIMENTAL and NOT production-ready**

1. **DO NOT use in production** - All configurations are experimental
2. **No reproducible bootc images exist** - Everything is still experimental
3. **Use only for testing** on virtual machines or test hardware
4. **Keep backups** of critical data and configurations
5. **Expect failures** - bootc is not stable on Debian yet
6. **Monitor bootc releases** for Debian compatibility improvements
7. **Contribute fixes** back to the bootc project

### For Development
1. **Use the hybrid approach**: Manual install + bootc management
2. **Validate images** using provided validation scripts
3. **Test with different kernel versions** for composefs features
4. **Contribute fixes** back to the bootc project

## Getting Help

### Documentation
- This repository: Comprehensive Debian-specific documentation
- [bootc upstream docs](https://bootc-dev.github.io/bootc/): Official documentation
- [OSTree documentation](https://ostreedev.github.io/ostree/): OSTree reference

### Community
- [bootc GitHub issues](https://github.com/containers/bootc/issues): Report bugs and issues
- [Debian bootc discussions](https://github.com/containers/bootc/discussions): Community discussions

### Reporting Issues
When reporting issues, please include:
- Debian version and kernel version
- bootc version and build method
- Complete error messages and logs
- Steps to reproduce the issue