apt-ostree/docs/BOOTC_IMAGE_GENERATION.md

Bootc Image Generation Documentation

Created: August 21, 2024
Last Updated: August 21, 2024
Status: 📋 Implementation Guide

Overview

The apt-ostree project includes a bootc image generation system that creates OCI-compatible container images from OSTree trees. This feature enables users to generate container images that can be used with bootc and other container orchestration systems.

Features

Working Features

• OSTree Tree Composition: Tree building from treefiles
• Package Management: APT integration with dependency resolution
• Container Generation: OCI image creation with manifests
• Multi-format Export: Docker archive and OCI formats
• Integrity Verification: SHA256 digest calculation
• End-to-end Workflow: Pipeline from treefile to image

Generated Image Contents

• Debian system with APT tools
• Bash shell and core utilities
• Systemd init system
• Requested packages and dependencies
• Filesystem structure
• OCI-compatible metadata

Usage

Basic Command Structure

apt-ostree compose tree <treefile> --container

Example Treefile (minimal-treefile.yaml)

ref: test/minimal
repos:
  - name: debian
    url: http://deb.debian.org/debian
    gpg-keys: []
packages:
  include:
    - bash
    - coreutils
    - grep
    - gawk
    - sed
    - systemd

Command Options

• --container: Generate container image
• --verbose: Enable verbose output
• --output-dir: Specify output directory
• --format: Choose output format (docker-archive, oci)

Architecture

Core Components

1. Treefile Parser

• YAML-based configuration
• Package specification and dependency management
• Repository configuration
• Customization options

2. Package Manager

• APT integration for package resolution
• Dependency calculation and installation
• Package cache management
• Cleanup and optimization

3. OSTree Integration

• Repository initialization and management
• Tree composition and commit creation
• Reference management
• Metadata handling

4. Container Generator

• OCI image structure creation
• Layer generation and compression
• Manifest and configuration files
• Multi-format export support

Workflow

Treefile → Package Resolution → OSTree Build → Container Generation → Export
    ↓              ↓                ↓              ↓              ↓
  Parse        Install Pkgs    Create Tree    Generate OCI    Save Files

Output Formats

1. Docker Archive (.tar)

• Format: Docker-compatible archive
• Contents:
  • manifest.json: Image metadata
  • repositories: Repository information
  • layer.tar: Filesystem content
  • config.json: Container configuration
• Size: ~358MB for minimal Debian system
• Compatibility: Loadable with podman, docker

2. OCI Image

• Format: OCI-compliant image structure
• Contents:
  • index.json: Image index
  • oci-layout: OCI specification version
  • blobs/: Image layers and metadata
• Compatibility: OCI-compliant tools and registries

Testing

Testing

The project includes a test script (test-compose-container.sh) that:

1. Builds test container with apt-ostree
2. Generates bootc image from minimal treefile
3. Validates output formats and structure
4. Tests image loading with podman
5. Verifies execution of generated images
6. Checks OCI structure and metadata

Test Results

Bootc image generation test completed
Summary:
   - Docker archive: 375070720 bytes (358MB)
   - OCI image: Structured
   - OSTree repo: Functional
   - Image execution: Successful

Integration

With bootc

Generated images are compatible with bootc:

• OCI structure
• Filesystem content
• System components
• Metadata

With Container Runtimes

• Podman: Supported and tested
• Docker: Compatible format
• containerd: OCI-compliant
• Other OCI tools: Standard compliance

Configuration

Environment Variables

• DEBIAN_FRONTEND: Package installation behavior
• RUST_LOG: Logging level for debugging
• OSTREE_SYSROOT: System root path

Build Options

• Workdir: Temporary build directory
• Repository: OSTree repository location
• Output formats: Multiple export options
• Verbosity: Detailed logging control

Troubleshooting

Common Issues

1. Permission Errors

# Ensure proper privileges for container operations
podman run --privileged -v $(pwd):/workspace:z apt-ostree-test

2. Package Installation Failures

• Check repository availability
• Verify package names and versions
• Ensure proper APT configuration

3. OSTree Errors

• Verify OSTree installation
• Check repository permissions
• Validate treefile syntax

Debug Mode

Enable verbose logging:

RUST_LOG=debug apt-ostree compose tree treefile.yaml --container --verbose

Performance

Build Times

• Minimal system: ~2-3 minutes
• Full desktop: ~10-15 minutes
• Custom packages: Varies by complexity

Resource Usage

• Memory: 2-4GB during build
• Disk: 5-10GB temporary space
• CPU: Multi-core utilization

Future Enhancements

Planned Features

• Incremental builds from parent references
• Parallel package installation for faster builds
• Custom base images support
• Multi-architecture builds
• Image signing and verification

Integration Goals

• CI/CD pipeline integration
• Registry push capabilities
• Testing frameworks
• Performance optimization

Examples

Minimal System

# Generate minimal Debian system
apt-ostree compose tree minimal-treefile.yaml --container --verbose

# Load and test the image
podman load -i output/test_minimal.tar
podman run --rm localhost/test/minimal:latest echo "Hello from bootc!"

Custom System

# Create custom treefile with additional packages
cat > custom-treefile.yaml << EOF
ref: custom/desktop
repos:
  - name: debian
    url: http://deb.debian.org/debian
packages:
  include:
    - gnome-shell
    - firefox-esr
    - libreoffice
EOF

# Generate custom image
apt-ostree compose tree custom-treefile.yaml --container

Conclusion

The bootc image generation system in apt-ostree provides a solution for creating container images from OSTree trees. With OCI compliance, testing, and integration capabilities, it serves as a replacement for rpm-ostree's container generation features in Debian-based systems.

The system has been tested and validated, demonstrating functionality suitable for development and testing environments.