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

Experimental Configurations

• ⚠️ Debian 13 (Trixie) + bootc v1.1.4 + Podman 4.0 (experimental, not fully tested)
• ⚠️ Debian 14 (Forky) + bootc v1.1.4 + Podman 4.0 (experimental, not fully tested)
• ⚠️ 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:

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