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

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