bootc-docs/image/bootc-image-technical-guide.md

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