apt-ostree/docs/INTEGRATION_HOWTO.md

apt-ostree Integration Howto

Overview

This document provides comprehensive guidance for external tools (like deb-bootc-compose) to integrate with apt-ostree's tree composition functionality. It covers the expected treefile format, API interfaces, and integration patterns.

Treefile Format Specification

Basic Structure

The apt-ostree treefile follows this YAML structure:

# apt-ostree treefile format
apiVersion: v1
kind: Treefile
metadata:
  name: "debian-trixie-base"
  description: "Base Debian Trixie system with apt-ostree"
  version: "0.1.0"
  parent: "debian-trixie-20250819"  # Optional: parent tree reference
  
spec:
  # Base system configuration
  base:
    distribution: "trixie"
    architecture: "amd64"
    mirror: "http://deb.debian.org/debian"
    
  # Package management
  packages:
    include:
      - "systemd"
      - "apt"
      - "ostree"
      - "bash"
      - "coreutils"
    exclude:
      - "unwanted-package"
      
  # Customizations
  customizations:
    users:
      - name: "admin"
        groups: ["sudo", "docker"]
        ssh_keys:
          - "ssh-rsa AAAAB3NzaC1..."
    
    files:
      - path: "/etc/hostname"
        content: "debian-atomic"
        mode: "0644"
        owner: "root:root"
        
    services:
      enable:
        - "systemd-networkd"
        - "systemd-resolved"
      disable:
        - "unwanted-service"
        
  # OSTree configuration
  ostree:
    ref: "debian/trixie/amd64/base"
    parent_ref: "debian/trixie/amd64/base"  # Optional
    commit_message: "Debian Trixie base system"
    
  # Build options
  build:
    parallel_jobs: 4
    cache_dir: "/var/cache/apt-ostree"
    cleanup: true

Required Fields

• apiVersion: Must be "v1"
• kind: Must be "Treefile"
• metadata.name: Unique identifier for the tree
• spec.base.distribution: Debian distribution (e.g., "trixie", "bookworm")
• spec.base.architecture: Target architecture (e.g., "amd64", "arm64")

Optional Fields

• metadata.parent: Reference to parent tree for incremental builds
• spec.packages.exclude: Packages to exclude from installation
• spec.customizations: System customizations (users, files, services)
• spec.ostree.parent_ref: Parent OSTree reference for delta generation

Integration Patterns

1. Command-Line Interface

External tools should use the apt-ostree compose command:

# Basic tree composition
apt-ostree compose --treefile treefile.yaml --output-dir /path/to/output

# With custom options
apt-ostree compose \
  --treefile treefile.yaml \
  --output-dir /path/to/output \
  --cache-dir /custom/cache \
  --parallel-jobs 8 \
  --verbose

# Validate treefile without building
apt-ostree compose --treefile treefile.yaml --validate-only

2. Programmatic Interface

For deeper integration, use the Rust library:

use apt_ostree::commands::compose::{TreeComposer, Treefile};

// Load and validate treefile
let treefile = Treefile::from_file("treefile.yaml")?;
treefile.validate()?;

// Create composer and build tree
let composer = TreeComposer::new(treefile);
let result = composer.compose_tree("/path/to/output")?;

// Access build artifacts
println!("Tree committed: {}", result.commit_hash);
println!("Archive created: {}", result.archive_path);

3. REST API (Future)

Planned REST API endpoints for cloud-native integration:

POST /api/v1/compose
Content-Type: application/json

{
  "treefile": "base64-encoded-yaml-content",
  "options": {
    "output_dir": "/path/to/output",
    "parallel_jobs": 4
  }
}

Treefile Validation

Schema Validation

The treefile must pass these validations:

1. YAML Syntax: Valid YAML format
2. Required Fields: All mandatory fields present
3. Field Types: Correct data types for each field
4. References: Valid OSTree references and package names
5. Security: Safe file paths and permissions

Validation Commands

# Validate treefile syntax and structure
apt-ostree compose --treefile treefile.yaml --validate-only

# Check for common issues
apt-ostree compose --treefile treefile.yaml --lint

Package Management Integration

Package Sources

External tools can specify custom package sources:

spec:
  packages:
    sources:
      - name: "custom-repo"
        url: "https://custom.debian.org/debian"
        distribution: "trixie"
        components: ["main", "contrib"]
        gpg_key: "base64-encoded-gpg-key"

Package Selection

Flexible package inclusion/exclusion:

spec:
  packages:
    include:
      - "package-name"
      - "package-name=version"
      - "package-name>=version"
    exclude:
      - "unwanted-package"
      - "conflicting-package"

Customization Hooks

Pre-Install Hooks

Execute commands before package installation:

spec:
  customizations:
    hooks:
      pre_install:
        - command: "mkdir -p /custom/directory"
        - command: "echo 'custom config' > /etc/custom.conf"

Post-Install Hooks

Execute commands after package installation:

spec:
  customizations:
    hooks:
      post_install:
        - command: "systemctl enable custom-service"
        - command: "update-alternatives --set editor /usr/bin/vim.basic"

OSTree Integration

Reference Management

External tools should manage OSTree references properly:

spec:
  ostree:
    ref: "debian/trixie/amd64/base"
    parent_ref: "debian/trixie/amd64/base"  # For incremental builds
    commit_message: "Custom Debian Trixie build"
    metadata:
      build_tool: "deb-bootc-compose"
      build_timestamp: "2025-08-19T18:44:29Z"
      build_version: "1.0.0"

Delta Generation

Enable efficient updates with static deltas:

spec:
  ostree:
    generate_deltas: true
    delta_refs:
      - "debian/trixie/amd64/base"
      - "debian/trixie/amd64/base"

Error Handling

Common Issues

1. Invalid Package Names: Check package existence before inclusion
2. Missing Dependencies: Ensure all required packages are specified
3. OSTree Conflicts: Handle reference conflicts gracefully
4. Permission Issues: Validate file paths and permissions

Error Response Format

{
  "error": "validation_failed",
  "message": "Invalid package name: non-existent-package",
  "details": {
    "field": "spec.packages.include[2]",
    "value": "non-existent-package",
    "suggestion": "Check package name spelling and availability"
  }
}

Best Practices

1. Treefile Design

• Use descriptive names and descriptions
• Include version information for reproducibility
• Document customizations clearly
• Test with minimal configurations first

2. Package Management

• Start with minimal package sets
• Use specific versions for critical packages
• Test package compatibility thoroughly
• Document package dependencies

3. Customization

• Keep customizations minimal and focused
• Use idempotent commands in hooks
• Validate file paths and permissions
• Test customizations in isolation

4. Integration Testing

• Test with various treefile configurations
• Validate error handling and edge cases
• Test incremental build scenarios
• Verify OSTree repository consistency

Migration Guide

From Other Tools

If migrating from other tree composition tools:

1. Analyze existing configuration
2. Map to apt-ostree treefile format
3. Test with equivalent configurations
4. Validate output consistency
5. Update CI/CD pipelines

Version Compatibility

• v1.0: Initial release format
• v1.1: Enhanced customization options (planned)
• v1.2: Advanced OSTree features (planned)

Support and Resources

Documentation

• apt-ostree User Guide
• Treefile Reference
• API Documentation

Community

• GitHub Issues
• Discussions
• Matrix Channel

Examples

See the examples/ directory for complete treefile examples and integration patterns.

---

Note: This document is maintained by the apt-ostree development team. For questions or suggestions, please open an issue or discussion on the project repository.