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

# 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

# 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

Tested Configurations

• ✅ Debian 13 (Trixie) + bootc v1.1.4 + Podman 4.0 (recommended)
• ✅ Debian 14 (Forky) + bootc v1.1.4 + Podman 4.0 (ideal)
• ⚠️ Debian 12 (Bookworm) + manual installation + bootc management (old OSTree)
• ⚠️ Debian 12 (Bookworm) + composefs backend (experimental, old OSTree)
• ❌ Debian 11 (Bullseye) - Not tested, may have issues

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:

# 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

1. Use Debian 13 (Trixie) as the minimum recommended version
2. Consider Debian 14 (Forky) for latest OSTree libraries
3. Backport OSTree from Forky to Trixie if needed
4. Use manual installation methods provided in this documentation
5. Test thoroughly on virtual machines before production deployment
6. Keep backups of critical data and configurations
7. Monitor bootc releases for Debian compatibility improvements

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: Official documentation
• OSTree documentation: OSTree reference

Community

• bootc GitHub issues: Report bugs and issues
• Debian 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