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

1312
image/bootc-image-external-commands.md Normal file
View file

File diff suppressed because it is too large Load diff

456
image/bootc-image-flowchart.md Normal file
View file

@ -0,0 +1,456 @@
# bootc image - Process Flowchart
## Overview
This document provides a visual representation of the `bootc image` process flow, showing the decision points, operations, and data structures involved in managing container images in the bootc storage system.
## Main Process Flow
```
┌─────────────────────────────────────────────────────────────────┐
│ bootc image │
└─────────────────────────────────────────────────────────────────┘
│
▼
┌─────────────────────────────────────────────────────────────────┐
│ Parse Command Arguments │
│ │
│ • Parse subcommand (list, copy-to-storage, etc.) │
│ • Parse command-specific options │
│ • Validate arguments │
└─────────────────────────────────────────────────────────────────┘
│
▼
┌─────────────────────────────────────────────────────────────────┐
│ Route to Subcommand │
│ │
│ ┌─────────────────────────────────────────────────────────────┐ │
│ │ Subcommand Type? │ │
│ └─────────────────────────────────────────────────────────────┘ │
│ │ │
│ ▼ │
│ ┌─────────────────┐ ┌─────────────────┐ ┌─────────────────┐ │
│ │ List │ │ Copy-to-Storage│ │ Pull-from-Default│ │
│ │ │ │ │ │ Storage │ │
│ │ ┌─────────────┐│ │ ┌─────────────┐│ │ ┌─────────────┐│ │
│ │ │ List Images ││ │ │ Copy Image ││ │ │ Pull Image ││ │
│ │ │ • Host ││ │ │ • Source ││ │ │ • From Host ││ │
│ │ │ • Logical ││ │ │ • Target ││ │ │ • To Bootc ││ │
│ │ │ • All ││ │ │ • Export ││ │ │ • Import ││ │
│ │ └─────────────┘│ │ └─────────────┘│ │ └─────────────┘│ │
│ └─────────────────┘ └─────────────────┘ └─────────────────┘ │
│ │ │ │ │
│ ▼ ▼ ▼ │
│ ┌─────────────────────────────────────────────────────────────┐ │
│ │ Cmd Wrapper │ │
│ │ │ │
│ │ • List: podman image list │ │
│ │ • Build: podman image build │ │
│ │ • Pull: podman image pull │ │
│ │ • Push: podman image push │ │
│ └─────────────────────────────────────────────────────────────┘ │
└─────────────────────────────────────────────────────────────────┘
│
▼
┌─────────────────────────────────────────────────────────────────┐
│ Success │
│ │
│ • Image operation completed successfully │
│ • Results displayed or returned │
│ • Storage updated if applicable │
└─────────────────────────────────────────────────────────────────┘
```
## Image Listing Flow
```
┌─────────────────────────────────────────────────────────────────┐
│ Image Listing Process │
└─────────────────────────────────────────────────────────────────┘
│
▼
┌─────────────────────────────────────────────────────────────────┐
│ Determine List Type │
│ │
│ ┌─────────────────────────────────────────────────────────────┐ │
│ │ List Type? │ │
│ └─────────────────────────────────────────────────────────────┘ │
│ │ │
│ ▼ │
│ ┌─────────────────┐ ┌─────────────────┐ ┌─────────────────┐ │
│ │ All │ │ Logical │ │ Host │ │
│ │ │ │ │ │ │ │
│ │ ┌─────────────┐│ │ ┌─────────────┐│ │ ┌─────────────┐│ │
│ │ │ List Both ││ │ │ List Only ││ │ │ List Only ││ │
│ │ │ • Host ││ │ │ Logical ││ │ │ Host ││ │
│ │ │ • Logical ││ │ │ Images ││ │ │ Images ││ │
│ │ │ Images ││ │ │ • Bound ││ │ │ • OSTree ││ │
│ │ │ Combined ││ │ │ Images ││ │ │ Repo ││ │
│ │ └─────────────┘│ │ └─────────────┘│ │ └─────────────┘│ │
│ └─────────────────┘ └─────────────────┘ └─────────────────┘ │
└─────────────────────────────────────────────────────────────────┘
│
▼
┌─────────────────────────────────────────────────────────────────┐
│ Check System Status │
│ │
│ ┌─────────────────────────────────────────────────────────────┐ │
│ │ System Booted? │ │
│ └─────────────────────────────────────────────────────────────┘ │
│ │ │
│ ▼ │
│ ┌─────────────────┐ ┌─────────────────────────────────────┐ │
│ │ Yes │ │ No │ │
│ │ │ │ │ │
│ │ ┌─────────────┐│ │ ┌─────────────────────────────────┐│ │
│ │ │ Get Storage ││ │ │ Use Root Filesystem ││ │
│ │ │ • OSTree ││ │ │ ││ │
│ │ │ Repo ││ │ │ • Query Bound Images ││ │
│ │ │ • Images ││ │ │ • List Logical Images ││ │
│ │ └─────────────┘│ │ └─────────────────────────────────┘│ │
│ └─────────────────┘ └─────────────────────────────────────┘ │
└─────────────────────────────────────────────────────────────────┘
│
▼
┌─────────────────────────────────────────────────────────────────┐
│ Query Images │
│ │
│ • Query OSTree repository for host images │
│ • Query bound images for logical images │
│ • Combine results based on list type │
│ • Format results according to output format │
└─────────────────────────────────────────────────────────────────┘
│
▼
┌─────────────────────────────────────────────────────────────────┐
│ Format Output │
│ │
│ ┌─────────────────────────────────────────────────────────────┐ │
│ │ Output Format? │ │
│ └─────────────────────────────────────────────────────────────┘ │
│ │ │
│ ▼ │
│ ┌─────────────────┐ ┌─────────────────────────────────────┐ │
│ │ Table │ │ JSON │ │
│ │ │ │ │ │
│ │ ┌─────────────┐│ │ ┌─────────────────────────────────┐│ │
│ │ │ Format as ││ │ │ Format as JSON ││ │
│ │ │ Table ││ │ │ ││ │
│ │ │ • Headers ││ │ │ • Pretty Print ││ │
│ │ │ • Rows ││ │ │ • Structured Data ││ │
│ │ │ • Columns ││ │ │ • Machine Readable ││ │
│ │ └─────────────┘│ │ └─────────────────────────────────┘│ │
│ └─────────────────┘ └─────────────────────────────────────┘ │
└─────────────────────────────────────────────────────────────────┘
```
## Image Copying Flow
```
┌─────────────────────────────────────────────────────────────────┐
│ Image Copying Process │
└─────────────────────────────────────────────────────────────────┘
│
▼
┌─────────────────────────────────────────────────────────────────┐
│ Determine Source and Target │
│ │
│ • Source: Use provided source or current booted image │
│ • Target: Use provided target or default (localhost/bootc) │
│ • Validate source and target formats │
└─────────────────────────────────────────────────────────────────┘
│
▼
┌─────────────────────────────────────────────────────────────────┐
│ Verify Source Image │
│ │
│ • Check if source image exists in bootc storage │
│ • Verify image integrity │
│ • Get image metadata │
└─────────────────────────────────────────────────────────────────┘
│
▼
┌─────────────────────────────────────────────────────────────────┐
│ Check Target Storage │
│ │
│ • Verify target storage is available │
│ • Check if target already exists │
│ • Prepare target storage if needed │
└─────────────────────────────────────────────────────────────────┘
│
▼
┌─────────────────────────────────────────────────────────────────┐
│ Copy Image │
│ │
│ • Use podman to copy image │
│ • Tag image with target name │
│ • Verify copy operation success │
└─────────────────────────────────────────────────────────────────┘
│
▼
┌─────────────────────────────────────────────────────────────────┐
│ Verify Copy │
│ │
│ • Check if target image exists │
│ • Verify image integrity │
│ • Update metadata │
└─────────────────────────────────────────────────────────────────┘
│
▼
┌─────────────────────────────────────────────────────────────────┐
│ Success │
│ │
│ • Image successfully copied │
│ • Target image available in containers-storage │
│ • Image ready for use with podman │
└─────────────────────────────────────────────────────────────────┘
```
## Image Pulling Flow
```
┌─────────────────────────────────────────────────────────────────┐
│ Image Pulling Process │
└─────────────────────────────────────────────────────────────────┘
│
▼
┌─────────────────────────────────────────────────────────────────┐
│ Validate Source Image │
│ │
│ • Check if source image exists in default storage │
│ • Verify image format and integrity │
│ • Get image metadata │
└─────────────────────────────────────────────────────────────────┘
│
▼
┌─────────────────────────────────────────────────────────────────┐
│ Prepare Bootc Storage │
│ │
│ • Ensure bootc storage is initialized │
│ • Create storage directories if needed │
│ • Set up storage configuration │
└─────────────────────────────────────────────────────────────────┘
│
▼
┌─────────────────────────────────────────────────────────────────┐
│ Copy from Host Storage │
│ │
│ • Use podman to copy from default storage │
│ • Set up storage roots and bindings │
│ • Copy image to bootc storage │
└─────────────────────────────────────────────────────────────────┘
│
▼
┌─────────────────────────────────────────────────────────────────┐
│ Verify Import │
│ │
│ • Check if image exists in bootc storage │
│ │ • Verify image integrity │
│ │ • Update metadata │
│ │ • Register with OSTree if needed │
└─────────────────────────────────────────────────────────────────┘
│
▼
┌─────────────────────────────────────────────────────────────────┐
│ Success │
│ │
│ • Image successfully imported │
│ • Image available in bootc storage │
│ • Image ready for deployment │
└─────────────────────────────────────────────────────────────────┘
```
## Podman Command Wrapper Flow
```
┌─────────────────────────────────────────────────────────────────┐
│ Podman Command Wrapper │
└─────────────────────────────────────────────────────────────────┘
│
▼
┌─────────────────────────────────────────────────────────────────┐
│ Parse Command │
│ │
│ • Determine podman subcommand (list, build, pull, push) │
│ • Parse command arguments │
│ • Validate command syntax │
└─────────────────────────────────────────────────────────────────┘
│
▼
┌─────────────────────────────────────────────────────────────────┐
│ Prepare Podman Command │
│ │
│ • Create podman command instance │
│ • Set up storage roots and bindings │
│ • Configure command arguments │
└─────────────────────────────────────────────────────────────────┘
│
▼
┌─────────────────────────────────────────────────────────────────┐
│ Execute Command │
│ │
│ • Run podman command with bootc storage │
│ • Capture output and error streams │
│ • Monitor command execution │
└─────────────────────────────────────────────────────────────────┘
│
▼
┌─────────────────────────────────────────────────────────────────┐
│ Handle Results │
│ │
│ • Check command exit status │
│ • Process output if needed │
│ • Handle errors appropriately │
└─────────────────────────────────────────────────────────────────┘
│
▼
┌─────────────────────────────────────────────────────────────────┐
│ Return Results │
│ │
│ • Return success or failure status │
│ • Pass through output to user │
│ • Update storage metadata if needed │
└─────────────────────────────────────────────────────────────────┘
```
## Storage Management Flow
```
┌─────────────────────────────────────────────────────────────────┐
│ Storage Management │
└─────────────────────────────────────────────────────────────────┘
│
▼
┌─────────────────────────────────────────────────────────────────┐
│ Check Storage Status │
│ │
│ • Verify bootc storage is initialized │
│ • Check storage configuration │
│ • Validate storage permissions │
└─────────────────────────────────────────────────────────────────┘
│
▼
┌─────────────────────────────────────────────────────────────────┐
│ Initialize Storage if Needed │
│ │
│ • Create storage directories │
│ • Set up storage configuration │
│ • Initialize storage metadata │
└─────────────────────────────────────────────────────────────────┘
│
▼
┌─────────────────────────────────────────────────────────────────┐
│ Perform Storage Operations │
│ │
│ • List images in storage │
│ • Check image existence │
│ • Pull/push images as needed │
│ • Update storage metadata │
└─────────────────────────────────────────────────────────────────┘
│
▼
┌─────────────────────────────────────────────────────────────────┐
│ Cleanup and Maintenance │
│ │
│ • Clean up temporary files │
│ • Update storage statistics │
│ • Perform garbage collection if needed │
└─────────────────────────────────────────────────────────────────┘
```
## Error Handling Flow
```
┌─────────────────────────────────────────────────────────────────┐
│ Error Detection │
└─────────────────────────────────────────────────────────────────┘
│
▼
┌─────────────────────────────────────────────────────────────────┐
│ Error Classification │
│ │
│ ┌─────────────────┐ ┌─────────────────┐ ┌─────────────────┐ │
│ │ Image │ │ Storage │ │ Podman │ │
│ │ Errors │ │ Errors │ │ Errors │ │
│ │ │ │ │ │ │ │
│ │ • Image not │ │ • Storage not │ │ • Command │ │
│ │ found │ │ available │ │ failed │ │
│ │ • Invalid │ │ • Permission │ │ • Invalid │ │
│ │ format │ │ denied │ │ arguments │ │
│ │ • Corrupted │ │ • Full storage │ │ • Network │ │
│ │ image │ │ • Configuration │ │ error │ │
│ │ │ │ error │ │ │ │
│ └─────────────────┘ └─────────────────┘ └─────────────────┘ │
└─────────────────────────────────────────────────────────────────┘
│
▼
┌─────────────────────────────────────────────────────────────────┐
│ Error Response │
│ │
│ • Display error message │
│ • Provide context information │
│ • Suggest remediation steps │
│ • Return appropriate exit code │
│ • Clean up any partial state │
└─────────────────────────────────────────────────────────────────┘
```
## State Transitions
```
┌─────────────────────────────────────────────────────────────────┐
│ Storage States │
└─────────────────────────────────────────────────────────────────┘
│
▼
┌─────────────────────────────────────────────────────────────────┐
│ Initial State │
│ │
│ ┌─────────────────────────────────────────────────────────────┐ │
│ │ Uninitialized Storage │ │
│ │ │ │
│ │ • No storage directories │ │
│ │ • No configuration │ │
│ │ • No images available │ │
│ └─────────────────────────────────────────────────────────────┘ │
│ │ │
│ ▼ │
│ ┌─────────────────────────────────────────────────────────────┐ │
│ │ Initialize Storage │ │
│ │ │ │
│ │ • Create storage directories │ │
│ │ • Set up configuration │ │
│ │ • Initialize metadata │ │
│ └─────────────────────────────────────────────────────────────┘ │
│ │ │
│ ▼ │
│ ┌─────────────────────────────────────────────────────────────┐ │
│ │ Initialized Storage │ │
│ │ │ │
│ │ • Storage directories exist │ │
│ │ • Configuration available │ │
│ │ • Ready for operations │ │
│ └─────────────────────────────────────────────────────────────┘ │
│ │ │
│ ▼ │
│ ┌─────────────────────────────────────────────────────────────┐ │
│ │ Image Operations │ │
│ │ │ │
│ │ • List images │ │
│ │ • Copy images │ │
│ │ • Pull images │ │
│ │ • Manage storage │ │
│ └─────────────────────────────────────────────────────────────┘ │
│ │ │
│ ▼ │
│ ┌─────────────────────────────────────────────────────────────┐ │
│ │ Active Storage with Images │ │
│ │ │ │
│ │ • Images stored and available │ │
│ │ • Operations working │ │
│ │ • Metadata up to date │ │
│ └─────────────────────────────────────────────────────────────┘ │
└─────────────────────────────────────────────────────────────────┘
```
This flowchart provides a comprehensive visual representation of the bootc image process, showing all decision points, operations, and state transitions involved in managing container images in the bootc storage system.

616
image/bootc-image-technical-guide.md Normal file
View file

@ -0,0 +1,616 @@
# bootc image - Technical Guide
## Overview
`bootc image` is a command for managing container images in the bootc storage system. It provides operations for listing, copying, and managing container images that are distinct from the standard `podman` image storage. The command operates on bootc's own container storage and provides integration with the broader container ecosystem.
## Purpose
The image command serves several critical functions:
1. **Image Listing**: List images stored in bootc storage
2. **Image Copying**: Copy images between storage systems
3. **Storage Management**: Manage bootc's container storage
4. **Podman Integration**: Provide wrapper commands for podman operations
5. **Image Discovery**: Discover and manage host and logical images
## Command Syntax
```bash
bootc image <COMMAND> [OPTIONS...]
```
### Available Commands
| Command | Description | Purpose |
|---------|-------------|---------|
| `list` | List fetched images stored in bootc storage | Display available images |
| `copy-to-storage` | Copy image from bootc storage to containers-storage | Export images |
| `pull-from-default-storage` | Copy image from default containers-storage to bootc storage | Import images |
| `cmd` | Wrapper for selected podman image subcommands | Podman integration |
## Architecture Overview
### 1. Image Command Structure
```rust
pub(crate) enum ImageOpts {
List {
list_type: ImageListType,
list_format: ImageListFormat,
},
CopyToStorage {
source: Option<String>,
target: Option<String>,
},
PullFromDefaultStorage {
image: String,
},
Cmd(ImageCmdOpts),
}
```
### 2. Image List Types
```rust
pub(crate) enum ImageListType {
All, // List all images
Logical, // List only logically bound images
Host, // List only host images
}
```
### 3. Image List Formats
```rust
pub(crate) enum ImageListFormat {
Table, // Human readable table format
Json, // JSON format
}
```
## Image Listing
### 1. List Command
```bash
# List all images
bootc image list
# List with specific type
bootc image list --type=host
# List in JSON format
bootc image list --format=json
```
### 2. Image Types
#### Host Images
- **Source**: Images stored in OSTree repository
- **Location**: `/sysroot/ostree/repo`
- **Purpose**: Images used by bootc deployments
- **Management**: Managed by bootc upgrade/switch
#### Logical Images
- **Source**: Images referenced by deployments
- **Location**: Bound image references
- **Purpose**: Images that can be deployed
- **Management**: Referenced but not necessarily stored locally
### 3. List Implementation
```rust
pub(crate) async fn list_images(list_type: ImageListType) -> Result<Vec<ImageOutput>> {
let rootfs = cap_std::fs::Dir::open_ambient_dir("/", cap_std::ambient_authority())?;
let sysroot = if ostree_booted()? {
Some(crate::cli::get_storage().await?)
} else {
None
};
Ok(match (list_type, sysroot) {
(ImageListType::All, None) => list_logical_images(&rootfs)?,
(ImageListType::All, Some(sysroot)) => list_host_images(&sysroot)?
.into_iter()
.chain(list_logical_images(&rootfs)?)
.collect(),
(ImageListType::Logical, _) => list_logical_images(&rootfs)?,
(ImageListType::Host, None) => {
bail!("Listing host images requires a booted bootc system")
}
(ImageListType::Host, Some(sysroot)) => list_host_images(&sysroot)?,
})
}
```
## Image Copying
### 1. Copy to Storage
```bash
# Copy current booted image to containers-storage
bootc image copy-to-storage
# Copy specific image to containers-storage
bootc image copy-to-storage --source=quay.io/myorg/debian-bootc:v2.0
# Copy to specific target
bootc image copy-to-storage --target=localhost/myimage:latest
```
**Purpose**: Export images from bootc storage to standard container storage
**Use Cases**:
- Making images available to podman
- Sharing images with other tools
- Backup and migration
### 2. Pull from Default Storage
```bash
# Pull image from default containers-storage
bootc image pull-from-default-storage quay.io/myorg/debian-bootc:v2.0
```
**Purpose**: Import images from standard container storage to bootc storage
**Use Cases**:
- Importing images built with podman
- Migrating images from other systems
- Testing with locally built images
### 3. Copy Implementation
```rust
pub(crate) async fn push_entrypoint(
source: Option<&str>,
target: Option<&str>,
) -> Result<()> {
let sysroot = get_storage().await?;
let imgstore = sysroot.get_ensure_imgstore()?;
let source = source.unwrap_or_else(|| {
// Get current booted image
get_current_booted_image(&sysroot)
});
let target = target.unwrap_or(IMAGE_DEFAULT);
// Copy image from bootc storage to containers-storage
imgstore.copy_to_containers_storage(&source, &target).await?;
Ok(())
}
```
## Podman Integration
### 1. Command Wrapper
```bash
# List images using podman
bootc image cmd list
# Build image using podman
bootc image cmd build -t myimage:latest .
# Pull image using podman
bootc image cmd pull quay.io/myorg/debian-bootc:v2.0
# Push image using podman
bootc image cmd push myimage:latest
```
### 2. Supported Commands
| Command | Description | Podman Equivalent |
|---------|-------------|-------------------|
| `list` | List images | `podman image list` |
| `build` | Build image | `podman image build` |
| `pull` | Pull image | `podman image pull` |
| `push` | Push image | `podman image push` |
### 3. Command Implementation
```rust
pub(crate) async fn imgcmd_entrypoint(
imgstore: &CStorage,
cmd: &str,
args: &[OsString],
) -> Result<()> {
let mut cmd = imgstore.new_image_cmd()?;
cmd.arg(cmd);
cmd.args(args);
let status = cmd.status()?;
if !status.success() {
std::process::exit(status.code().unwrap_or(1));
}
Ok(())
}
```
## Storage Management
### 1. Bootc Storage
**Location**: `/var/lib/bootc/containers/`
**Purpose**: Bootc's dedicated container storage
**Features**:
- Isolated from system podman storage
- Optimized for bootc operations
- Integrated with OSTree
### 2. Storage Operations
#### List Images
```rust
pub(crate) async fn list_images(&self) -> Result<Vec<ImageListEntry>> {
let mut cmd = self.new_image_cmd()?;
cmd.args(["list", "--format=json"]);
cmd.stdin(Stdio::null());
let mut stdout = tempfile::tempfile()?;
cmd.stdout(stdout.try_clone()?);
let status = cmd.status()?;
if !status.success() {
// Handle error
}
// Parse JSON output
stdout.rewind()?;
let images: Vec<ImageListEntry> = serde_json::from_reader(stdout)?;
Ok(images)
}
```
#### Check Image Exists
```rust
pub(crate) async fn exists(&self, image: &str) -> Result<bool> {
let mut cmd = AsyncCommand::from(self.new_image_cmd()?);
cmd.args(["exists", image]);
Ok(cmd.status().await?.success())
}
```
#### Pull Image
```rust
pub(crate) async fn pull(&self, image: &str, mode: PullMode) -> Result<bool> {
match mode {
PullMode::IfNotExists => {
if self.exists(image).await? {
return Ok(false);
}
}
PullMode::Always => {}
};
let mut cmd = self.new_image_cmd()?;
cmd.args(["pull", image]);
let status = cmd.status()?;
Ok(status.success())
}
```
## Image Types and Sources
### 1. Host Images
**Definition**: Images stored in the OSTree repository
**Location**: `/sysroot/ostree/repo`
**Management**: Managed by bootc operations
**Use Cases**: Deployed images, system images
```rust
fn list_host_images(sysroot: &crate::store::Storage) -> Result<Vec<ImageOutput>> {
let ostree = sysroot.get_ostree()?;
let repo = ostree.repo();
let images = ostree_ext::container::store::list_images(&repo)?;
Ok(images
.into_iter()
.map(|img| ImageOutput {
image_type: ImageListTypeColumn::Host,
image: img,
})
.collect())
}
```
### 2. Logical Images
**Definition**: Images referenced by deployments but not necessarily stored
**Location**: Bound image references
**Management**: Referenced by deployment configurations
**Use Cases**: Available for deployment, referenced images
```rust
fn list_logical_images(rootfs: &Dir) -> Result<Vec<ImageOutput>> {
let bound_images = query_bound_images(rootfs)?;
Ok(bound_images
.into_iter()
.map(|img| ImageOutput {
image_type: ImageListTypeColumn::Logical,
image: img.image,
})
.collect())
}
```
## Image Operations
### 1. Image Copying Process
```rust
pub(crate) async fn copy_to_containers_storage(
&self,
source: &str,
target: &str,
) -> Result<()> {
// 1. Verify source image exists
if !self.exists(source).await? {
bail!("Source image not found: {}", source);
}
// 2. Create target storage if needed
self.ensure_storage_exists()?;
// 3. Copy image using podman
let mut cmd = self.new_image_cmd()?;
cmd.args(["tag", source, target]);
let status = cmd.status()?;
if !status.success() {
bail!("Failed to copy image: {}", source);
}
Ok(())
}
```
### 2. Image Pulling Process
```rust
pub(crate) async fn pull_from_host_storage(&self, image: &str) -> Result<()> {
let mut cmd = Command::new("podman");
cmd.stdin(Stdio::null());
cmd.stdout(Stdio::null());
// Set up storage roots
let temp_runroot = TempDir::new(cap_std::ambient_authority())?;
bind_storage_roots(&mut cmd, &self.storage_root, &temp_runroot)?;
// Copy from host storage to bootc storage
let storage_dest = &format!(
"containers-storage:[overlay@{}+/proc/self/fd/{}]",
STORAGE_ALIAS_DIR, STORAGE_RUN_FD
);
cmd.args(["tag", image, storage_dest]);
let status = cmd.status()?;
if !status.success() {
bail!("Failed to pull image from host storage: {}", image);
}
Ok(())
}
```
## Error Handling
### 1. Common Errors
#### Image Not Found
```bash
Error: Source image not found: quay.io/myorg/debian-bootc:v2.0
```
**Solution**: Verify image exists in bootc storage
```bash
bootc image list
```
#### Storage Not Available
```bash
Error: Bootc storage not available
```
**Solution**: Check storage initialization
```bash
bootc status
```
#### Permission Denied
```bash
Error: Permission denied
```
**Solution**: Run with appropriate privileges
```bash
sudo bootc image list
```
### 2. Error Recovery
#### Storage Corruption
```bash
# Reinitialize storage
bootc image cmd prune -a
# Rebuild storage
bootc image cmd build --no-cache
```
#### Image Corruption
```bash
# Remove corrupted image
bootc image cmd rmi corrupted-image
# Re-pull image
bootc image cmd pull quay.io/myorg/debian-bootc:v2.0
```
## Integration Patterns
### 1. Development Workflow
```bash
# Build image with podman
bootc image cmd build -t myimage:latest .
# Copy to bootc storage
bootc image copy-to-storage --source=myimage:latest
# Deploy image
bootc switch myimage:latest
```
### 2. Production Workflow
```bash
# Pull production image
bootc image cmd pull quay.io/myorg/debian-bootc:v2.0
# Copy to bootc storage
bootc image copy-to-storage --source=quay.io/myorg/debian-bootc:v2.0
# Deploy image
bootc switch quay.io/myorg/debian-bootc:v2.0
```
### 3. Backup and Migration
```bash
# List all images
bootc image list --format=json > images.json
# Copy images to standard storage
bootc image copy-to-storage --source=image1
bootc image copy-to-storage --source=image2
# Export with podman
podman save -o backup.tar localhost/bootc
```
## Performance Considerations
### 1. Storage Efficiency
**Image Deduplication**: Bootc storage uses OSTree for efficient storage
**Layer Sharing**: Common layers are shared between images
**Compression**: Images are compressed for storage efficiency
### 2. Operation Performance
**Parallel Operations**: Multiple operations can run in parallel
**Caching**: Frequently accessed images are cached
**Lazy Loading**: Images are loaded on demand
### 3. Storage Management
**Cleanup**: Regular cleanup of unused images
**Garbage Collection**: Automatic garbage collection of unused layers
**Space Monitoring**: Monitor storage usage
## Security Considerations
### 1. Image Verification
**Signature Verification**: Images are verified using container signatures
**Integrity Checks**: Image integrity is verified during operations
**Access Control**: Proper access control for storage operations
### 2. Storage Isolation
**Separate Storage**: Bootc storage is isolated from system storage
**Permission Management**: Proper permissions for storage access
**Audit Logging**: Operations are logged for audit purposes
## Troubleshooting
### 1. Common Issues
#### Images Not Listed
```bash
# Check storage status
bootc status
# Verify storage initialization
ls -la /var/lib/bootc/containers/
```
#### Copy Operations Fail
```bash
# Check source image
bootc image list
# Check target storage
podman images
```
#### Podman Commands Fail
```bash
# Check podman installation
podman --version
# Check storage configuration
podman info
```
### 2. Debug Commands
```bash
# Enable debug logging
RUST_LOG=debug bootc image list
# Check storage details
bootc image cmd list --format=json
# Verify image integrity
bootc image cmd inspect image-name
```
## Best Practices
### 1. Image Management
- **Regular Cleanup**: Clean up unused images regularly
- **Image Tagging**: Use meaningful tags for images
- **Version Control**: Keep track of image versions
- **Backup Strategy**: Implement backup strategy for important images
### 2. Storage Management
- **Monitor Usage**: Monitor storage usage regularly
- **Optimize Storage**: Use efficient storage configurations
- **Cleanup Policies**: Implement cleanup policies
- **Backup Storage**: Backup storage configurations
### 3. Integration
- **Automation**: Automate image operations where possible
- **Monitoring**: Monitor image operations
- **Documentation**: Document image management procedures
- **Testing**: Test image operations regularly
## Future Enhancements
### 1. Planned Features
- **Image Signing**: Enhanced image signing capabilities
- **Image Encryption**: Image encryption support
- **Advanced Filtering**: More advanced image filtering
- **Bulk Operations**: Bulk image operations
### 2. Integration Improvements
- **Registry Integration**: Better registry integration
- **CI/CD Integration**: Enhanced CI/CD integration
- **Monitoring Integration**: Better monitoring integration
- **API Support**: REST API for image operations
This technical guide provides comprehensive understanding of the bootc image system's architecture, implementation, and usage patterns.