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

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

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

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

```http
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

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

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

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

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

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

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

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

```json
{
  "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](USER_GUIDE.md)
- [Treefile Reference](TREEFILE_REFERENCE.md)
- [API Documentation](API_REFERENCE.md)

### Community

- [GitHub Issues](https://github.com/particle-os/apt-ostree/issues)
- [Discussions](https://github.com/particle-os/apt-ostree/discussions)
- [Matrix Channel](https://matrix.to/#/#apt-ostree:matrix.org)

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