particle-os/bootc-docs
1
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions

Initial commit: Comprehensive Debian bootc documentation

Browse source 
- 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
This commit is contained in:
robojerk 2025-09-15 14:02:28 -07:00
commit 526f1c1afd
67 changed files with 34174 additions and 0 deletions
Download patch file Download diff file Expand all files Collapse all files

419
internals/bootc-internals-flowchart.md Normal file
View file

@ -0,0 +1,419 @@
# bootc internals - Process Flowchart
## Overview
This document provides a visual representation of the `bootc internals` process flow, showing the decision points, operations, and data structures involved in internal system operations.
## Main Process Flow
```
┌─────────────────────────────────────────────────────────────────┐
│ bootc internals │
└─────────────────────────────────────────────────────────────────┘
│
▼
┌─────────────────────────────────────────────────────────────────┐
│ Parse Command Arguments │
│ │
│ • Parse internals subcommand │
│ • Parse command-specific options │
│ • Validate arguments │
└─────────────────────────────────────────────────────────────────┘
│
▼
┌─────────────────────────────────────────────────────────────────┐
│ Route to Subcommand │
│ │
│ ┌─────────────────────────────────────────────────────────────┐ │
│ │ Subcommand Type? │ │
│ └─────────────────────────────────────────────────────────────┘ │
│ │ │
│ ▼ │
│ ┌─────────────────┐ ┌─────────────────┐ ┌─────────────────┐ │
│ │ Systemd │ │ Filesystem │ │ Proxy │ │
│ │ Generator │ │ Operations │ │ Commands │ │
│ │ │ │ │ │ │ │
│ │ ┌─────────────┐│ │ ┌─────────────┐│ │ ┌─────────────┐│ │
│ │ │ Generate ││ │ │ Fsck ││ │ │ OstreeExt ││ │
│ │ │ Units ││ │ │ Cleanup ││ │ │ Cfs ││ │
│ │ │ Fix Fstab ││ │ │ Relabel ││ │ │ OstreeCont ││ │
│ │ └─────────────┘│ │ │ Fsverity ││ │ └─────────────┘│ │
│ └─────────────────┘ │ └─────────────┘│ └─────────────────┘ │
│ │ │ │
│ ┌─────────────────┐ │ ┌─────────────────┐ ┌─────────────────┐ │
│ │ Testing │ │ │ System │ │ Development │ │
│ │ Commands │ │ │ Operations │ │ Tools │ │
│ │ │ │ │ │ │ │ │
│ │ ┌─────────────┐│ │ │ ┌─────────────┐│ │ ┌─────────────┐│ │
│ │ │ TestComp ││ │ │ │ Reboot ││ │ │ PrintSchema ││ │
│ │ │ Loopback ││ │ │ │ InstallComp ││ │ │ DumpCliJson ││ │
│ │ │ DirDiff ││ │ │ │ RhsmFacts ││ │ │ DirDiff ││ │
│ │ └─────────────┘│ │ │ └─────────────┘│ │ └─────────────┘│ │
│ └─────────────────┘ │ └─────────────────┘ └─────────────────┘ │
└─────────────────────────────────────────────────────────────────┘
│
▼
┌─────────────────────────────────────────────────────────────────┐
│ Success │
│ │
│ • Internal operation completed successfully │
│ • Results displayed or logged │
│ • System state updated if applicable │
└─────────────────────────────────────────────────────────────────┘
```
## Systemd Generator Flow
```
┌─────────────────────────────────────────────────────────────────┐
│ Systemd Generator Process │
└─────────────────────────────────────────────────────────────────┘
│
▼
┌─────────────────────────────────────────────────────────────────┐
│ Check System State │
│ │
│ • Check if system is ostree-booted │
│ • Verify /etc/fstab exists │
│ • Check for existing bootc stamps │
└─────────────────────────────────────────────────────────────────┘
│
▼
┌─────────────────────────────────────────────────────────────────┐
│ Analyze /etc/fstab │
│ │
│ ┌─────────────────────────────────────────────────────────────┐ │
│ │ Fstab Analysis │ │
│ └─────────────────────────────────────────────────────────────┘ │
│ │ │
│ ▼ │
│ ┌─────────────────┐ ┌─────────────────────────────────────┐ │
│ │ From Anaconda │ │ Not From Anaconda │ │
│ │ │ │ │ │
│ │ ┌─────────────┐│ │ ┌─────────────────────────────────┐│ │
│ │ │ Generate ││ │ │ No Action Needed ││ │
│ │ │ Fstab Editor││ │ │ ││ │
│ │ │ Service ││ │ │ • Return false ││ │
│ │ │ ││ │ │ • Exit cleanly ││ │
│ │ └─────────────┘│ │ └─────────────────────────────────┘│ │
│ └─────────────────┘ └─────────────────────────────────────┘ │
└─────────────────────────────────────────────────────────────────┘
│
▼
┌─────────────────────────────────────────────────────────────────┐
│ Generate Systemd Unit │
│ │
│ • Create bootc-fstab-edit.service │
│ • Set up service dependencies │
│ • Configure service execution │
└─────────────────────────────────────────────────────────────────┘
│
▼
┌─────────────────────────────────────────────────────────────────┐
│ Success │
│ │
│ • Systemd unit generated successfully │
│ • Service ready for execution │
│ • Fstab will be updated on next boot │
└─────────────────────────────────────────────────────────────────┘
```
## Filesystem Consistency Check Flow
```
┌─────────────────────────────────────────────────────────────────┐
│ Fsck Process │
└─────────────────────────────────────────────────────────────────┘
│
▼
┌─────────────────────────────────────────────────────────────────┐
│ Initialize Storage │
│ │
│ • Get storage instance │
│ • Open OSTree repository │
│ • Prepare output stream │
└─────────────────────────────────────────────────────────────────┘
│
▼
┌─────────────────────────────────────────────────────────────────┐
│ Run Consistency Checks │
│ │
│ ┌─────────────────────────────────────────────────────────────┐ │
│ │ Check Type? │ │
│ └─────────────────────────────────────────────────────────────┘ │
│ │ │
│ ▼ │
│ ┌─────────────────┐ ┌─────────────────┐ ┌─────────────────┐ │
│ │ OSTree │ │ Composefs │ │ Deployment │ │
│ │ Repository │ │ Repository │ State │ │
│ │ │ │ │ │ │
│ │ ┌─────────────┐│ │ ┌─────────────┐│ │ ┌─────────────┐│ │
│ │ │ Check Repo ││ │ │ Check Repo ││ │ │ Check Depl ││ │
│ │ │ Integrity ││ │ │ Integrity ││ │ │ States ││ │
│ │ │ Validate ││ │ │ Validate ││ │ │ Validate ││ │
│ │ │ Objects ││ │ │ Images ││ │ │ Configs ││ │
│ │ └─────────────┘│ │ └─────────────┘│ │ └─────────────┘│ │
│ └─────────────────┘ └─────────────────┘ └─────────────────┘ │
└─────────────────────────────────────────────────────────────────┘
│
▼
┌─────────────────────────────────────────────────────────────────┐
│ Report Results │
│ │
│ • Display check results │
│ • Report any errors found │
│ • Provide recommendations │
└─────────────────────────────────────────────────────────────────┘
│
▼
┌─────────────────────────────────────────────────────────────────┐
│ Success │
│ │
│ • All checks completed │
│ │ • System integrity verified │
│ │ • Issues reported if found │
│ │ • Recommendations provided │
└─────────────────────────────────────────────────────────────────┘
```
## Cleanup Operations Flow
```
┌─────────────────────────────────────────────────────────────────┐
│ Cleanup Process │
└─────────────────────────────────────────────────────────────────┘
│
▼
┌─────────────────────────────────────────────────────────────────┐
│ Initialize Storage │
│ │
│ • Get storage instance │
│ • Open OSTree repository │
│ • Prepare cleanup operations │
└─────────────────────────────────────────────────────────────────┘
│
▼
┌─────────────────────────────────────────────────────────────────┐
│ Identify Cleanup Targets │
│ │
│ • Find old deployments │
│ • Identify unused container images │
│ • Locate temporary files │
│ • Check for orphaned data │
└─────────────────────────────────────────────────────────────────┘
│
▼
┌─────────────────────────────────────────────────────────────────┐
│ Perform Cleanup │
│ │
│ ┌─────────────────────────────────────────────────────────────┐ │
│ │ Cleanup Type? │ │
│ └─────────────────────────────────────────────────────────────┘ │
│ │ │
│ ▼ │
│ ┌─────────────────┐ ┌─────────────────┐ ┌─────────────────┐ │
│ │ Deployments │ │ Images │ │ Temporary │ │
│ │ │ │ │ │ Files │ │
│ │ ┌─────────────┐│ │ ┌─────────────┐│ │ ┌─────────────┐│ │
│ │ │ Remove Old ││ │ │ Remove ││ │ │ Remove ││ │
│ │ │ Deployments ││ │ │ Unused ││ │ │ Temp Files ││ │
│ │ │ Clean Refs ││ │ │ Images ││ │ │ Clean Cache ││ │
│ │ └─────────────┘│ │ └─────────────┘│ │ └─────────────┘│ │
│ └─────────────────┘ └─────────────────┘ └─────────────────┘ │
└─────────────────────────────────────────────────────────────────┘
│
▼
┌─────────────────────────────────────────────────────────────────┐
│ Garbage Collection │
│ │
│ • Run OSTree garbage collection │
│ • Clean up repository objects │
│ • Update repository metadata │
└─────────────────────────────────────────────────────────────────┘
│
▼
┌─────────────────────────────────────────────────────────────────┐
│ Success │
│ │
│ • Cleanup completed successfully │
│ • Storage space freed │
│ • System optimized │
└─────────────────────────────────────────────────────────────────┘
```
## Proxy Commands Flow
```
┌─────────────────────────────────────────────────────────────────┐
│ Proxy Commands Process │
└─────────────────────────────────────────────────────────────────┘
│
▼
┌─────────────────────────────────────────────────────────────────┐
│ Determine Proxy Type │
│ │
│ ┌─────────────────────────────────────────────────────────────┐ │
│ │ Proxy Type? │ │
│ └─────────────────────────────────────────────────────────────┘ │
│ │ │
│ ▼ │
│ ┌─────────────────┐ ┌─────────────────┐ ┌─────────────────┐ │
│ │ OstreeExt │ │ Cfs │ │ OstreeCont │ │
│ │ │ │ │ │ │ │
│ │ ┌─────────────┐│ │ ┌─────────────┐│ │ ┌─────────────┐│ │
│ │ │ Parse Args ││ │ │ Parse Args ││ │ │ Parse Args ││ │
│ │ │ Call CLI ││ │ │ Call CLI ││ │ │ Call CLI ││ │
│ │ │ Return ││ │ │ Return ││ │ │ Return ││ │
│ │ │ Results ││ │ │ Results ││ │ │ Results ││ │
│ │ └─────────────┘│ │ └─────────────┘│ │ └─────────────┘│ │
│ └─────────────────┘ └─────────────────┘ └─────────────────┘ │
└─────────────────────────────────────────────────────────────────┘
│
▼
┌─────────────────────────────────────────────────────────────────┐
│ Execute Proxy Command │
│ │
│ • Forward arguments to target CLI │
│ • Execute command with proper context │
│ • Return results to caller │
└─────────────────────────────────────────────────────────────────┘
│
▼
┌─────────────────────────────────────────────────────────────────┐
│ Success │
│ │
│ • Proxy command executed successfully │
│ • Results returned to caller │
│ • Target CLI completed │
└─────────────────────────────────────────────────────────────────┘
```
## Testing Commands Flow
```
┌─────────────────────────────────────────────────────────────────┐
│ Testing Commands Process │
└─────────────────────────────────────────────────────────────────┘
│
▼
┌─────────────────────────────────────────────────────────────────┐
│ Determine Test Type │
│ │
│ ┌─────────────────────────────────────────────────────────────┐ │
│ │ Test Type? │ │
│ └─────────────────────────────────────────────────────────────┘ │
│ │ │
│ ▼ │
│ ┌─────────────────┐ ┌─────────────────┐ ┌─────────────────┐ │
│ │ TestComp │ │ Loopback │ │ DirDiff │ │
│ │ │ │ │ │ │ │
│ │ ┌─────────────┐│ │ ┌─────────────┐│ │ ┌─────────────┐│ │
│ │ │ Init Repo ││ │ │ Create Dev ││ │ │ Setup Dirs ││ │
│ │ │ Write Test ││ │ │ Test Ops ││ │ │ Run Merge ││ │
│ │ │ Verify ││ │ │ Cleanup ││ │ │ Verify ││ │
│ │ └─────────────┘│ │ └─────────────┘│ │ └─────────────┘│ │
│ └─────────────────┘ └─────────────────┘ └─────────────────┘ │
└─────────────────────────────────────────────────────────────────┘
│
▼
┌─────────────────────────────────────────────────────────────────┐
│ Execute Test │
│ │
│ • Run test operations │
│ • Verify expected results │
│ • Clean up test data │
└─────────────────────────────────────────────────────────────────┘
│
▼
┌─────────────────────────────────────────────────────────────────┐
│ Success │
│ │
│ • Test completed successfully │
│ • Results verified │
│ • System state restored │
└─────────────────────────────────────────────────────────────────┘
```
## Error Handling Flow
```
┌─────────────────────────────────────────────────────────────────┐
│ Error Detection │
└─────────────────────────────────────────────────────────────────┘
│
▼
┌─────────────────────────────────────────────────────────────────┐
│ Error Classification │
│ │
│ ┌─────────────────┐ ┌─────────────────┐ ┌─────────────────┐ │
│ │ System │ │ Permission │ │ Resource │ │
│ │ Errors │ │ Errors │ │ Errors │ │
│ │ │ │ │ │ │ │
│ │ • Not Root │ │ • Access Denied │ │ • Out of Space │ │
│ │ • Not Booted │ │ • Invalid Path │ │ • Memory Error │ │
│ │ • Invalid State │ │ • File Not Found│ │ • Device Error │ │
│ │ │ │ │ │ │ │
│ └─────────────────┘ └─────────────────┘ └─────────────────┘ │
└─────────────────────────────────────────────────────────────────┘
│
▼
┌─────────────────────────────────────────────────────────────────┐
│ Error Response │
│ │
│ • Display error message │
│ • Provide context information │
│ • Suggest remediation steps │
│ • Return appropriate exit code │
│ • Clean up any partial state │
└─────────────────────────────────────────────────────────────────┘
```
## State Transitions
```
┌─────────────────────────────────────────────────────────────────┐
│ System States │
└─────────────────────────────────────────────────────────────────┘
│
▼
┌─────────────────────────────────────────────────────────────────┐
│ Initial State │
│ │
│ ┌─────────────────────────────────────────────────────────────┐ │
│ │ System Ready │ │
│ │ │ │
│ │ • All services running │ │
│ │ • Storage available │ │
│ │ • Permissions correct │ │
│ └─────────────────────────────────────────────────────────────┘ │
│ │ │
│ ▼ │
│ ┌─────────────────────────────────────────────────────────────┐ │
│ │ Execute Command │ │
│ │ │ │
│ │ • Parse arguments │ │
│ │ • Validate inputs │ │
│ │ • Check prerequisites │ │
│ └─────────────────────────────────────────────────────────────┘ │
│ │ │
│ ▼ │
│ ┌─────────────────────────────────────────────────────────────┐ │
│ │ Processing State │ │
│ │ │ │
│ │ • Command executing │ │
│ │ • System state changing │ │
│ │ • Resources being used │ │
│ └─────────────────────────────────────────────────────────────┘ │
│ │ │
│ ▼ │
│ ┌─────────────────────────────────────────────────────────────┐ │
│ │ Final State │ │
│ │ │ │
│ │ • Command completed │ │
│ │ • System state updated │ │
│ │ • Resources cleaned up │ │
│ └─────────────────────────────────────────────────────────────┘ │
└─────────────────────────────────────────────────────────────────┘
```
This flowchart provides a comprehensive visual representation of the bootc internals process, showing all decision points, operations, and state transitions involved in internal system operations.