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

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