adecc24db1
- Add comprehensive fix for grub2-mkconfig composefs incompatibility - Document the critical issue from Red Hat Bugzilla #2308594 - Provide complete patch, automated script, and Containerfile integration - Add troubleshooting documentation with verification steps - Update COMPATIBILITY.md with critical issue warning - Update README.md to highlight this critical fix This fix is ESSENTIAL for all composefs-based bootc images to boot properly. Without this fix, grub2-mkconfig will generate incorrect configurations and cause boot failures. Based on: - Red Hat Bugzilla #2308594 (reported by Colin Walters) - ostree issue #3198 - Affects all bootc/ostree systems using composefs
285 lines
No EOL
12 KiB
Markdown
285 lines
No EOL
12 KiB
Markdown
# Debian bootc Documentation
|
|
|
|
This repository contains comprehensive technical documentation for the `bootc` project, specifically tailored for Debian systems. The documentation covers all aspects of bootc functionality, from basic usage to advanced technical implementation details.
|
|
|
|
## Overview
|
|
|
|
`bootc` is a tool for managing bootable container images using OCI/Docker container images as a transport and delivery format for base OS updates. It provides transactional, in-place operating system updates using container images. **The bootc binary does not actually make bootc images.**
|
|
|
|
## Documentation Structure
|
|
|
|
### Core Commands
|
|
|
|
#### Installation
|
|
- **`install/`** - Complete installation system documentation
|
|
- `technical-installation-guide.md` - Comprehensive technical guide
|
|
- `installation-flowchart.md` - Process flowcharts
|
|
- `external-commands-reference.md` - External command dependencies
|
|
- `source-code-analysis.md` - Rust source code analysis
|
|
|
|
#### Container Operations
|
|
- **`lint/`** - Container image validation
|
|
- `bootc-lint-guide.md` - User guide
|
|
- `technical-reference.md` - Technical implementation
|
|
- `examples-and-troubleshooting.md` - Practical examples
|
|
- `quick-reference.md` - Quick reference
|
|
|
|
- **`upgrade/`** - System updates
|
|
- `bootc-upgrade-guide.md` - User guide
|
|
- `technical-reference.md` - Technical implementation
|
|
- `examples-and-troubleshooting.md` - Practical examples
|
|
- `quick-reference.md` - Quick reference
|
|
- `external-commands-reference.md` - External commands
|
|
|
|
#### System Management
|
|
- **`edit/`** - Declarative configuration management
|
|
- `bootc-edit-technical-guide.md` - Technical guide
|
|
- `bootc-edit-flowchart.md` - Process flowchart
|
|
- `bootc-edit-external-commands.md` - External commands
|
|
|
|
- **`switch/`** - Image switching
|
|
- `bootc-switch-technical-guide.md` - Technical guide
|
|
- `bootc-switch-flowchart.md` - Process flowchart
|
|
- `bootc-switch-external-commands.md` - External commands
|
|
|
|
- **`rollback/`** - System rollback
|
|
- `bootc-rollback-technical-guide.md` - Technical guide
|
|
- `bootc-rollback-flowchart.md` - Process flowchart
|
|
- `bootc-rollback-external-commands.md` - External commands
|
|
|
|
- **`status/`** - System status
|
|
- `bootc-status-technical-guide.md` - Technical guide
|
|
- `bootc-status-flowchart.md` - Process flowchart
|
|
- `bootc-status-external-commands.md` - External commands
|
|
|
|
- **`usr-overlay/`** - Temporary /usr modifications
|
|
- `bootc-usr-overlay-technical-guide.md` - Technical guide
|
|
- `bootc-usr-overlay-flowchart.md` - Process flowchart
|
|
- `bootc-usr-overlay-external-commands.md` - External commands
|
|
|
|
### Hidden/Internal Commands
|
|
|
|
#### Image Management
|
|
- **`image/`** - Container image operations
|
|
- `bootc-image-technical-guide.md` - Technical guide
|
|
- `bootc-image-flowchart.md` - Process flowchart
|
|
- `bootc-image-external-commands.md` - External commands
|
|
|
|
#### Internal Operations
|
|
- **`internals/`** - Internal system operations
|
|
- `bootc-internals-technical-guide.md` - Technical guide
|
|
- `bootc-internals-flowchart.md` - Process flowcharts
|
|
- `bootc-internals-external-commands.md` - External commands
|
|
- `bootc-internals-architecture.md` - System architecture
|
|
- `bootc-internals-examples-troubleshooting.md` - Examples and troubleshooting
|
|
- `bootc-internals-quick-reference.md` - Quick reference
|
|
|
|
#### State Management
|
|
- **`state/`** - System state operations
|
|
- `bootc-state-technical-guide.md` - Technical guide
|
|
- `bootc-state-flowchart.md` - Process flowchart
|
|
- `bootc-state-external-commands.md` - External commands
|
|
- `bootc-state-examples-troubleshooting.md` - Examples and troubleshooting
|
|
- `bootc-state-quick-reference.md` - Quick reference
|
|
|
|
#### Namespace Operations
|
|
- **`exec-in-host-mount-namespace/`** - Host namespace execution
|
|
- `bootc-exec-in-host-mount-namespace-technical-guide.md` - Technical guide
|
|
- `bootc-exec-in-host-mount-namespace-flowchart.md` - Process flowchart
|
|
- `bootc-exec-in-host-mount-namespace-external-commands.md` - External commands
|
|
- `bootc-exec-in-host-mount-namespace-examples-troubleshooting.md` - Examples and troubleshooting
|
|
- `bootc-exec-in-host-mount-namespace-quick-reference.md` - Quick reference
|
|
|
|
#### Composefs Backend
|
|
- **`composefs-finalize-staged/`** - Composefs deployment finalization
|
|
- `bootc-composefs-finalize-staged-technical-guide.md` - Technical guide
|
|
- `bootc-composefs-finalize-staged-flowchart.md` - Process flowchart
|
|
- `bootc-composefs-finalize-staged-external-commands.md` - External commands
|
|
- `bootc-composefs-finalize-staged-examples-troubleshooting.md` - Examples and troubleshooting
|
|
- `bootc-composefs-finalize-staged-quick-reference.md` - Quick reference
|
|
|
|
### Specialized Documentation
|
|
|
|
#### Composefs Integration
|
|
- **`composefs.md`** - Technical report on composefs integration
|
|
- Architecture comparison between main and composefs-backend branches
|
|
- Implementation details and source code examples
|
|
- External commands and process flows
|
|
- Kernel and userspace requirements
|
|
|
|
#### Compatibility Information
|
|
- **`COMPATIBILITY.md`** - Version compatibility matrix
|
|
- Tested versions and configurations
|
|
- Feature compatibility matrix
|
|
- Known issues and workarounds
|
|
- Debian-specific considerations
|
|
|
|
#### Building and Development
|
|
- **`building/`** - Image building guidance
|
|
- `guidance.md` - Building guidance (corrected for /usr/etc handling)
|
|
- `bootc-runtime.md` - Runtime configuration
|
|
- `users-and-groups.md` - User and group management
|
|
- `kernel-arguments.md` - Kernel argument management
|
|
- `secrets.md` - Secret management
|
|
- `management-services.md` - Management services
|
|
- `base-images.md` - Creating base bootc images (OCI and debbootstrap methods)
|
|
- `base-images-wo-bootc.md` - Creating bootc images without bootc binary (Debian-specific)
|
|
- `initramfs-integration.md` - Essential initramfs files for composefs support
|
|
|
|
#### Troubleshooting
|
|
- `troubleshooting/grub2-composefs-fix.md` - **CRITICAL**: Fix for grub2-mkconfig composefs incompatibility
|
|
|
|
#### Installation
|
|
- **`installation.md`** - Installation instructions (corrected for source compilation)
|
|
|
|
## Key Features
|
|
|
|
### Comprehensive Coverage
|
|
- **All Commands**: Every bootc command and subcommand documented
|
|
- **Technical Depth**: Rust source code analysis and implementation details
|
|
- **Practical Focus**: Real-world examples and troubleshooting guides
|
|
- **Debian-Specific**: Adapted for Debian package management and conventions
|
|
|
|
### Hidden Functionality Discovered
|
|
- **Hidden Commands**: `bootc image`, `bootc internals`, `bootc state`, `bootc exec-in-host-mount-namespace`
|
|
- **Hidden Options**: `--progress-fd`, `--no-signature-verification`, `--mutate-in-place`, `--json`, `--target-no-signature-verification`
|
|
- **Feature Flags**: `composefs-backend`, `install-to-disk`, `rhsm`, `docgen`
|
|
- **Composefs Commands**: `bootc composefs-finalize-staged` (composefs-backend branch only)
|
|
|
|
### Advanced Features
|
|
- **Anaconda Integration**: Special support for Anaconda installer environments
|
|
- **Supermin Workarounds**: Container environment compatibility fixes
|
|
- **Buildah Integration**: Container build system integration
|
|
- **RHSM Support**: Red Hat Subscription Manager integration (feature flag)
|
|
- **Documentation Generation**: CLI structure dumping for documentation (feature flag)
|
|
- **Manual Installation**: Bypass bootc installation issues on Debian
|
|
- **Hybrid Management**: Manual installation + bootc management operations
|
|
- **Composefs Backend**: Alternative filesystem backend with EROFS support
|
|
|
|
## Technical Insights
|
|
|
|
### Architecture
|
|
- **OSTree Backend**: Primary backend using OSTree for deployments
|
|
- **Composefs Backend**: Alternative backend using EROFS and composefs
|
|
- **Container Integration**: Full OCI/Docker container image support
|
|
- **Transactional Updates**: Atomic, rollback-capable system updates
|
|
|
|
### Security
|
|
- **AppArmor Support**: Debian-specific security labeling
|
|
- **Signature Verification**: Container image signature validation
|
|
- **Sandboxing**: Systemd service sandboxing for security
|
|
- **Namespace Isolation**: Mount namespace operations for container safety
|
|
|
|
### Performance
|
|
- **EROFS Integration**: Efficient compressed filesystem for composefs backend
|
|
- **Delta Updates**: Efficient update mechanisms
|
|
- **Caching**: Image and metadata caching for performance
|
|
- **Parallel Operations**: Concurrent processing where possible
|
|
|
|
## Usage
|
|
|
|
### Installation
|
|
```bash
|
|
# Install build dependencies
|
|
sudo apt update
|
|
sudo apt install -y build-essential git pkg-config libostree-dev libglib2.0-dev libgpgme-dev libseccomp-dev
|
|
|
|
# Install runtime dependencies
|
|
sudo apt install -y ostree podman
|
|
|
|
# Clone and build bootc
|
|
git clone https://github.com/containers/bootc.git
|
|
cd bootc
|
|
make
|
|
sudo make install
|
|
```
|
|
|
|
### Basic Usage
|
|
```bash
|
|
# Check system status
|
|
bootc status
|
|
|
|
# Install from container image
|
|
bootc install to-filesystem quay.io/myorg/myimage:latest
|
|
|
|
# Update system
|
|
bootc upgrade
|
|
|
|
# Switch to different image
|
|
bootc switch quay.io/myorg/newimage:latest
|
|
```
|
|
|
|
### Debian-Specific Workarounds
|
|
|
|
#### Manual Installation (Recommended for Debian)
|
|
```bash
|
|
# Build bootc-compatible image without bootc binary
|
|
./build-bootc-base-wo-bootc.sh
|
|
|
|
# Install manually to filesystem
|
|
./install-bootc-manual.sh debian-bootc-base:latest /mnt/sysroot
|
|
|
|
# Install bootc for management operations
|
|
./install-bootc-for-management.sh
|
|
|
|
# Use bootc for upgrades and management
|
|
./bootc-manage.sh status
|
|
./bootc-manage.sh upgrade
|
|
```
|
|
|
|
#### Adding Application Layers
|
|
```bash
|
|
# Build nginx layer on base image
|
|
podman build -f examples/nginx/Containerfile -t debian-bootc-nginx:latest .
|
|
|
|
# Install with nginx layer
|
|
./build-and-install-nginx.sh /mnt/sysroot
|
|
|
|
# Test the installation
|
|
./test-nginx-layer.sh debian-bootc-nginx:latest
|
|
```
|
|
|
|
## Debian-Specific Considerations
|
|
|
|
### Why This Documentation Exists
|
|
- **bootc Reliability Issues**: bootc may be unreliable on Debian due to Fedora-centric development
|
|
- **Missing Dependencies**: Some bootc dependencies may not be available in Debian
|
|
- **Compilation Issues**: Rust dependencies may not compile cleanly on Debian
|
|
- **Runtime Errors**: Even if compiled, bootc may fail at runtime on Debian systems
|
|
|
|
### Our Solution
|
|
- **Manual Installation**: Bypass bootc installation issues with manual filesystem setup
|
|
- **Hybrid Approach**: Manual installation + bootc management for best of both worlds
|
|
- **Validation Scripts**: Manual validation of bootc-compatible images
|
|
- **Complete Workflows**: Ready-to-use scripts for common operations
|
|
|
|
### Key Files for Debian Users
|
|
- `building/base-images-wo-bootc.md` - Complete guide for creating bootc images without bootc binary
|
|
- `building/base-images.md` - Standard methods for creating base images
|
|
- `troubleshooting/grub2-composefs-fix.md` - **CRITICAL**: Fix for grub2-mkconfig composefs incompatibility
|
|
- All command documentation includes Debian-specific adaptations
|
|
|
|
## Contributing
|
|
|
|
This documentation is maintained alongside the bootc project. When contributing:
|
|
|
|
1. Ensure all commands and options are documented
|
|
2. Include technical implementation details
|
|
3. Provide practical examples and troubleshooting
|
|
4. Maintain Debian-specific adaptations
|
|
5. Update flowcharts and external command references
|
|
6. Test manual installation workflows on Debian
|
|
7. Validate that workarounds actually work
|
|
|
|
## License
|
|
|
|
This documentation is released into the public domain under the Unlicense. You are free to use, modify, distribute, and sell this work without any restrictions or attribution requirements.
|
|
|
|
See [LICENSE](LICENSE) for details.
|
|
|
|
## References
|
|
|
|
- [bootc GitHub Repository](https://github.com/containers/bootc)
|
|
- [OSTree Documentation](https://ostreedev.github.io/ostree/)
|
|
- [Composefs Documentation](https://github.com/containers/composefs)
|
|
- [Debian Documentation](https://www.debian.org/doc/) |