bootc-docs/COMPATIBILITY.md

# Compatibility Matrix

This document provides compatibility information for bootc on Debian systems.

## Tested Versions

| Component | Version | Notes |
|-----------|---------|-------|
| **bootc** | v1.1.4+ | Tested with main branch |
| **Debian Base** | 13 (Trixie) | Recommended (stable) |
| **Debian Base** | 14 (Forky) | Ideal (testing, latest OSTree) |
| **Debian Base** | 12 (Bookworm) | Not recommended (oldstable, old OSTree) |
| **Kernel** | 6.1+ | Minimum for basic features |
| **Podman** | 4.0+ | Required for container operations |
| **OSTree** | 2024.1+ | Required for deployments (Trixie+) |
| **OSTree** | 2023.1+ | Minimum (Bookworm has older version) |

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

## Composefs Backend Requirements

### Kernel Requirements
- **Minimum**: Kernel 5.15+ for basic EROFS support
- **Recommended**: Kernel 6.5+ for full composefs features
- **Overlay/Verity**: Kernel 6.6+ for advanced integrity features

### Userspace Requirements
- **composefs**: Userspace composefs tools
- **EROFS**: Enhanced Read-Only File System support
- **fsverity**: File system verification support

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

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