particle-os/bootc-docs
1
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions
bootc-docs/README.md
robojerk adecc24db1
Some checks failed
Test bootc Documentation / test-base-image (push) Failing after 27s
Details
Test bootc Documentation / test-documentation (push) Failing after 31s
Details
Add critical grub2-mkconfig composefs compatibility fix 
- 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
2025-09-15 15:38:16 -07:00

12 KiB
Raw Permalink Blame History

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

# 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 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 for details.

References