particle-os/bootc-docs
1
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions
bootc-docs/README.md
robojerk 0e12ed215a
Some checks failed
Test bootc Documentation / test-base-image (push) Failing after 26s
Details
Test bootc Documentation / test-documentation (push) Failing after 37s
Details
Change license to public domain (Unlicense) 
- Replace Apache 2.0 with Unlicense (public domain)
- No attribution required - maximum freedom
- Anyone can use, modify, distribute, sell without restrictions
- Update README to reflect public domain status

This provides the most permissive licensing possible with no
requirements for attribution or credit.
2025-09-15 14:33:24 -07:00

280 lines
No EOL
11 KiB
Markdown
Raw 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)
#### 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 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/)
Reference in a new issue View git blame Copy permalink