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
```bash
apt-ostree compose tree <treefile> --container
```

### Example Treefile (minimal-treefile.yaml)
```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
```bash
# 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:
```bash
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
```bash
# 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
```bash
# 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.