apt-ostree/docs/INTEGRATION_HOWTO.md

apt-ostree Integration Howto

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

Overview

This document provides guidance for external tools to integrate with apt-ostree's tree composition functionality. It covers the actual treefile format, command interface, and integration patterns based on the current implementation.

Treefile Format Specification

Basic Structure

The apt-ostree treefile follows this YAML structure:

# apt-ostree treefile format
# OSTree repository configuration
ostree:
  ref: apt-ostree/test/debian/trixie
  repo: /tmp/apt-ostree-test/repo

# Base system (required)
base: debian:trixie

# APT package sources
apt:
  sources:
    - "deb http://deb.debian.org/debian trixie main contrib non-free"
    - "deb http://deb.debian.org/debian trixie-updates main contrib non-free"
    - "deb http://deb.debian.org/debian trixie-security main contrib non-free"

# Packages to install
packages:
  # Base system packages
  - debian-minimal
  - systemd
  - ostree
  - apt
  - dpkg

  # Essential utilities
  - bash
  - coreutils
  - curl
  - wget
  - gnupg
  - ca-certificates

# System configuration
system:
  # Enable systemd services
  services:
    - systemd-networkd
    - systemd-resolved

  # Create basic directory structure
  directories:
    - /etc/apt-ostree
    - /var/lib/apt-ostree
    - /usr/lib/bootc

# Post-installation scripts (optional)
postinstall:
  - echo "apt-ostree test system created successfully"
  - echo "OSTree ref: apt-ostree/test/debian/trixie"

Required Fields

• ostree.ref: Unique identifier for the tree
• base: Base system specification (e.g., "debian:trixie")
• apt.sources: Package repository sources
• packages: List of packages to install

Optional Fields

• ostree.repo: OSTree repository path
• system.services: Systemd services to enable
• system.directories: Directories to create
• postinstall: Post-installation commands

Integration Patterns

1. Command-Line Interface

External tools should use the apt-ostree compose tree command:

# Basic tree composition
apt-ostree compose tree treefile.yaml

# With container generation
apt-ostree compose tree treefile.yaml --container --verbose

# With custom repository path
apt-ostree compose tree treefile.yaml --repo /custom/repo/path --container

2. Programmatic Interface

For deeper integration, use the Rust library:

use apt_ostree::commands::compose::{compose_tree, ComposeOptions};

// Create compose options
let mut options = ComposeOptions::default();
options.generate_container = true;
options.verbose = true;

// Compose tree
let commit_hash = compose_tree("treefile.yaml", None, &options).await?;
println!("Tree committed: {}", commit_hash);

3. Container Generation

To generate bootc-compatible container images:

# Generate OCI/Docker image
apt-ostree compose tree treefile.yaml --container --verbose

# Output will be in the current directory or specified location
# Generates both OCI image and Docker archive formats

Treefile Validation

Basic Validation

The treefile must pass these validations:

1. YAML Syntax: Valid YAML format
2. Required Fields: All mandatory fields present
3. Package Names: Valid Debian package names
4. Repository URLs: Accessible package repositories

Validation Process

# Basic syntax check
yamllint treefile.yaml

# Test with apt-ostree (will fail fast on invalid configurations)
apt-ostree compose tree treefile.yaml --verbose

Package Management Integration

Package Sources

External tools can specify custom package sources:

apt:
  sources:
    - "deb http://deb.debian.org/debian trixie main contrib non-free"
    - "deb http://custom.debian.org/debian trixie main"
    - "deb [arch=amd64] http://custom.repo.com/debian trixie main"

Package Selection

Package inclusion is straightforward:

packages:
  - "package-name"
  - "package-name=version"
  - "package-name>=version"

System Customization

Service Management

Enable systemd services:

system:
  services:
    - systemd-networkd
    - systemd-resolved
    - ssh

Directory Creation

Create custom directories:

system:
  directories:
    - /etc/myapp
    - /var/lib/myapp
    - /usr/local/bin

Post-Install Scripts

Execute commands after package installation:

postinstall:
  - "echo 'Custom configuration' > /etc/myapp/config.conf"
  - "systemctl enable myapp-service"
  - "update-alternatives --set editor /usr/bin/vim.basic"

OSTree Integration

Reference Management

Manage OSTree references:

ostree:
  ref: "debian/trixie/amd64/myapp"
  repo: "/srv/ostree/repo"

Repository Structure

The generated OSTree repository follows this structure:

repo/
├── objects/
├── refs/
│   └── heads/
│       └── debian/trixie/amd64/myapp
└── config

Error Handling

Common Issues

1. Invalid Package Names: Check package existence in repositories
2. Repository Access: Ensure package sources are accessible
3. Permission Issues: Verify write access to OSTree repository
4. Disk Space: Ensure sufficient space for tree composition

Error Response

apt-ostree provides error messages for common issues:

# Package not found
Error: Package 'non-existent-package' not found in repositories

# Repository access issue
Error: Failed to fetch package lists from http://deb.debian.org/debian

# Permission denied
Error: Permission denied: cannot write to OSTree repository

Best Practices

1. Treefile Design

• Use descriptive reference names
• Start with minimal package sets
• Test with basic configurations first
• Document customizations clearly

2. Package Management

• Use specific versions for critical packages
• Test package compatibility
• Minimize package dependencies
• Use official Debian repositories when possible

3. System Configuration

• Keep customizations minimal and focused
• Use idempotent commands in postinstall
• Test customizations in isolation
• Validate service configurations

4. Integration Testing

• Test with various treefile configurations
• Validate error handling
• Test container generation
• 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

• Current: Basic tree composition and container generation
• Future: Enhanced customization options and validation

Support and Resources

Documentation

• apt-ostree User Guide
• Bootc Image Generation
• Project Overview

Examples

See the tests/ directory for complete treefile examples:

• tests/test-treefile.yaml - Basic Debian system
• minimal-treefile.yaml - Minimal system for testing

Community

• GitHub Issues
• Project Repository

Current Limitations

What's Available

• Basic tree composition from treefiles
• Package installation via APT
• OSTree repository management
• Container image generation
• System customization via postinstall scripts

What's Not Available

• REST API interface
• Advanced validation and linting
• Delta generation
• GPG package verification
• Complex customization hooks
• Multi-architecture support

Future Enhancements

Planned Features

• Enhanced treefile validation
• Advanced customization options
• Multi-architecture support
• Performance optimization
• Extended testing capabilities

---

Note: This document reflects the current state of apt-ostree. For questions or suggestions, please open an issue on the project repository.