Initial commit: Comprehensive Debian bootc documentation

- Complete documentation for all bootc commands and subcommands - Debian-specific adaptations and workarounds - Manual installation methods to bypass bootc reliability issues - Technical guides with Rust source code analysis - Flowcharts and external command references - Hidden command documentation (bootc internals, state, etc.) - Composefs integration analysis - Base image creation guides (with and without bootc binary) - Management scripts and automation - Comprehensive troubleshooting and examples
2025-09-15 14:02:28 -07:00 · 2025-09-15 14:02:28 -07:00 · 526f1c1afd
commit 526f1c1afd
67 changed files with 34174 additions and 0 deletions
--- a/README.md
+++ b/README.md
@ -0,0 +1,270 @@
+# 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
+
+#### 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)
+
+#### 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
+- 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 follows the same license as the bootc project.
+
+## 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/)