particle-os/bootc-docs
1
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions
bootc-docs/COMPATIBILITY.md
robojerk d2238df478 Critical safety and compatibility fixes based on ChatGPT feedback 
SAFETY FIXES:
- Add prominent safety warnings for destructive operations
- Add BOOTC_I_KNOW_THIS_WIPES_MY_DISK environment variable checks
- Add safety warnings to manual installation scripts

BUILD FIXES:
- Fix Containerfile systemd calls to use symlinks instead of systemctl
- Replace brittle image validation with podman image mount
- Add fallback for rootless/mount issues

COMPATIBILITY FIXES:
- Align Debian version references (12 Bookworm vs 14 Forky)
- Add comprehensive COMPATIBILITY.md with version matrix
- Add kernel requirements for composefs (5.15+ basic, 6.5+ recommended)
- Document experimental flags and version requirements

TECHNICAL IMPROVEMENTS:
- Use DEBIAN_FRONTEND=noninteractive in build scripts
- Improve image inspection robustness
- Add explicit version testing matrix
- Document known issues and workarounds

This addresses the most critical issues identified in the ChatGPT review:
1. Safety warnings for destructive operations
2. Build-time systemd handling fixes
3. Robust image validation methods
4. Version compatibility documentation
2025-09-15 14:19:12 -07:00

4.8 KiB
Raw Blame History

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 12 (Bookworm) Primary target
Kernel 6.1+ Minimum for basic features
Podman 4.0+ Required for container operations
OSTree 2023.1+ Required for deployments

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

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

Testing Matrix

Tested Configurations

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

Untested Configurations

  • Debian 13 (Trixie) - Future release
  • Debian 14 (Forky) - Future release
  • Other Debian derivatives (Ubuntu, etc.)

Recommendations

For Production Use

  1. Use manual installation methods provided in this documentation
  2. Test thoroughly on virtual machines before production deployment
  3. Keep backups of critical data and configurations
  4. 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

Community

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