No description
bd4c3e746f
- Add comprehensive technical implementation details based on actual Python source - Document all command-line options and usage patterns - Add detailed examples for build-rootfs, rechunk, and list commands - Include practical Containerfile examples for different use cases - Document external dependencies and error handling - Add security considerations and cleanup procedures - Provide cross-build examples and advanced workflows Based on analysis of the actual bootc-base-imagectl Python script from https://gitlab.com/fedora/bootc/base-images/-/raw/main/bootc-base-imagectl |
||
|---|---|---|
| .github/workflows | ||
| building | ||
| composefs-finalize-staged | ||
| edit | ||
| exec-in-host-mount-namespace | ||
| image | ||
| install | ||
| internals | ||
| lint | ||
| rollback | ||
| state | ||
| status | ||
| switch | ||
| upgrade | ||
| usr-overlay | ||
| .gitignore | ||
| bootc-base-imagectl.md | ||
| COMPATIBILITY.md | ||
| composefs.md | ||
| installation.md | ||
| intro.md | ||
| LICENSE | ||
| ostree.md | ||
| README.md | ||
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 documentationtechnical-installation-guide.md- Comprehensive technical guideinstallation-flowchart.md- Process flowchartsexternal-commands-reference.md- External command dependenciessource-code-analysis.md- Rust source code analysis
Container Operations
-
lint/- Container image validationbootc-lint-guide.md- User guidetechnical-reference.md- Technical implementationexamples-and-troubleshooting.md- Practical examplesquick-reference.md- Quick reference
-
upgrade/- System updatesbootc-upgrade-guide.md- User guidetechnical-reference.md- Technical implementationexamples-and-troubleshooting.md- Practical examplesquick-reference.md- Quick referenceexternal-commands-reference.md- External commands
System Management
-
edit/- Declarative configuration managementbootc-edit-technical-guide.md- Technical guidebootc-edit-flowchart.md- Process flowchartbootc-edit-external-commands.md- External commands
-
switch/- Image switchingbootc-switch-technical-guide.md- Technical guidebootc-switch-flowchart.md- Process flowchartbootc-switch-external-commands.md- External commands
-
rollback/- System rollbackbootc-rollback-technical-guide.md- Technical guidebootc-rollback-flowchart.md- Process flowchartbootc-rollback-external-commands.md- External commands
-
status/- System statusbootc-status-technical-guide.md- Technical guidebootc-status-flowchart.md- Process flowchartbootc-status-external-commands.md- External commands
-
usr-overlay/- Temporary /usr modificationsbootc-usr-overlay-technical-guide.md- Technical guidebootc-usr-overlay-flowchart.md- Process flowchartbootc-usr-overlay-external-commands.md- External commands
Hidden/Internal Commands
Image Management
image/- Container image operationsbootc-image-technical-guide.md- Technical guidebootc-image-flowchart.md- Process flowchartbootc-image-external-commands.md- External commands
Internal Operations
internals/- Internal system operationsbootc-internals-technical-guide.md- Technical guidebootc-internals-flowchart.md- Process flowchartsbootc-internals-external-commands.md- External commandsbootc-internals-architecture.md- System architecturebootc-internals-examples-troubleshooting.md- Examples and troubleshootingbootc-internals-quick-reference.md- Quick reference
State Management
state/- System state operationsbootc-state-technical-guide.md- Technical guidebootc-state-flowchart.md- Process flowchartbootc-state-external-commands.md- External commandsbootc-state-examples-troubleshooting.md- Examples and troubleshootingbootc-state-quick-reference.md- Quick reference
Namespace Operations
exec-in-host-mount-namespace/- Host namespace executionbootc-exec-in-host-mount-namespace-technical-guide.md- Technical guidebootc-exec-in-host-mount-namespace-flowchart.md- Process flowchartbootc-exec-in-host-mount-namespace-external-commands.md- External commandsbootc-exec-in-host-mount-namespace-examples-troubleshooting.md- Examples and troubleshootingbootc-exec-in-host-mount-namespace-quick-reference.md- Quick reference
Composefs Backend
composefs-finalize-staged/- Composefs deployment finalizationbootc-composefs-finalize-staged-technical-guide.md- Technical guidebootc-composefs-finalize-staged-flowchart.md- Process flowchartbootc-composefs-finalize-staged-external-commands.md- External commandsbootc-composefs-finalize-staged-examples-troubleshooting.md- Examples and troubleshootingbootc-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 guidanceguidance.md- Building guidance (corrected for /usr/etc handling)bootc-runtime.md- Runtime configurationusers-and-groups.md- User and group managementkernel-arguments.md- Kernel argument managementsecrets.md- Secret managementmanagement-services.md- Management servicesbase-images.md- Creating base bootc images (OCI and debbootstrap methods)base-images-wo-bootc.md- Creating bootc images without bootc binary (Debian-specific)
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
# 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
# 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)
# 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
# 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 binarybuilding/base-images.md- Standard methods for creating base images- All command documentation includes Debian-specific adaptations
Contributing
This documentation is maintained alongside the bootc project. When contributing:
- Ensure all commands and options are documented
- Include technical implementation details
- Provide practical examples and troubleshooting
- Maintain Debian-specific adaptations
- Update flowcharts and external command references
- Test manual installation workflows on Debian
- 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 for details.