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:

```yaml
# 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:

```bash
# 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:

```rust
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:

```bash
# 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

```bash
# 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:

```yaml
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:

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

## System Customization

### Service Management

Enable systemd services:

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

### Directory Creation

Create custom directories:

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

### Post-Install Scripts

Execute commands after package installation:

```yaml
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:

```yaml
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:

```bash
# 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](USER_GUIDE.md)
- [Bootc Image Generation](BOOTC_IMAGE_GENERATION.md)
- [Project Overview](PROJECT_OVERVIEW.md)

### 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](https://github.com/your-org/apt-ostree/issues)
- [Project Repository](https://github.com/your-org/apt-ostree)

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