From 15b981d38f16ed1608862883731beb50b16160f2 Mon Sep 17 00:00:00 2001
From: robojerk <rraines@gmail.com>
Date: Tue, 19 Aug 2025 11:55:41 -0700
Subject: [PATCH] docs: create comprehensive integration howto for external
 tools

- Add INTEGRATION_HOWTO.md with complete treefile format specification
- Include example treefile (debian-trixie-base.yaml) for deb-bootc-compose
- Document integration patterns: CLI, Rust library, and future REST API
- Cover validation, error handling, best practices, and migration guide
- Address format mismatch between deb-bootc-compose and apt-ostree
- Provide clear documentation for external tool integration
---
 docs/INTEGRATION_HOWTO.md        | 354 +++++++++++++++++++++++++++++++
 examples/README.md               | 106 +++++++++
 examples/debian-trixie-base.yaml |  98 +++++++++
 3 files changed, 558 insertions(+)
 create mode 100644 docs/INTEGRATION_HOWTO.md
 create mode 100644 examples/README.md
 create mode 100644 examples/debian-trixie-base.yaml

diff --git a/docs/INTEGRATION_HOWTO.md b/docs/INTEGRATION_HOWTO.md
new file mode 100644
index 00000000..d18f02d5
--- /dev/null
+++ b/docs/INTEGRATION_HOWTO.md
@@ -0,0 +1,354 @@
+# 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.
diff --git a/examples/README.md b/examples/README.md
new file mode 100644
index 00000000..c528af31
--- /dev/null
+++ b/examples/README.md
@@ -0,0 +1,106 @@
+# apt-ostree Examples
+
+This directory contains example treefiles and integration patterns for `apt-ostree`.
+
+## Example Treefiles
+
+### `debian-trixie-base.yaml`
+A complete example of a Debian Trixie base system treefile that demonstrates:
+- Basic treefile structure and required fields
+- Package inclusion and exclusion patterns
+- User and file customizations
+- Service management
+- OSTree reference configuration
+- Build options
+
+## Usage
+
+### 1. Validate the Example
+
+```bash
+# Validate the treefile syntax and structure
+apt-ostree compose --treefile examples/debian-trixie-base.yaml --validate-only
+```
+
+### 2. Build the Example
+
+```bash
+# Build the tree using the example configuration
+apt-ostree compose \
+  --treefile examples/debian-trixie-base.yaml \
+  --output-dir /tmp/debian-trixie-output
+```
+
+### 3. Customize for Your Needs
+
+Copy the example and modify it for your specific requirements:
+
+```bash
+cp examples/debian-trixie-base.yaml my-custom-tree.yaml
+# Edit my-custom-tree.yaml with your customizations
+```
+
+## Integration Patterns
+
+### For deb-bootc-compose
+
+The example treefile shows the exact format that `deb-bootc-compose` should use:
+
+```yaml
+apiVersion: v1
+kind: Treefile
+metadata:
+  name: "your-tree-name"
+  # ... other metadata
+spec:
+  base:
+    distribution: "trixie"
+    architecture: "amd64"
+  # ... rest of specification
+```
+
+### For Other Tools
+
+External tools can use the same format and integrate via:
+- Command-line interface (`apt-ostree compose`)
+- Rust library (`apt_ostree::commands::compose`)
+- Future REST API endpoints
+
+## Testing
+
+### Validation Tests
+
+```bash
+# Test YAML syntax
+yamllint examples/debian-trixie-base.yaml
+
+# Test apt-ostree validation
+apt-ostree compose --treefile examples/debian-trixie-base.yaml --validate-only
+```
+
+### Build Tests
+
+```bash
+# Test actual tree composition
+apt-ostree compose \
+  --treefile examples/debian-trixie-base.yaml \
+  --output-dir /tmp/test-output \
+  --verbose
+```
+
+## Contributing
+
+When adding new examples:
+
+1. **Follow the established format** from existing examples
+2. **Include comprehensive comments** explaining each section
+3. **Test the example** before committing
+4. **Update this README** to document the new example
+5. **Ensure portability** across different environments
+
+## Support
+
+For questions about these examples or help with customizations:
+- Check the [Integration Howto](../docs/INTEGRATION_HOWTO.md)
+- Open an issue on the project repository
+- Join the community discussions
diff --git a/examples/debian-trixie-base.yaml b/examples/debian-trixie-base.yaml
new file mode 100644
index 00000000..955c1e04
--- /dev/null
+++ b/examples/debian-trixie-base.yaml
@@ -0,0 +1,98 @@
+# Example apt-ostree treefile for Debian Trixie base system
+# This demonstrates the format that external tools should use
+
+apiVersion: v1
+kind: Treefile
+metadata:
+  name: "debian-trixie-base"
+  description: "Base Debian Trixie system with essential packages"
+  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:
+      # Essential system packages
+      - "systemd"
+      - "apt"
+      - "ostree"
+      - "bash"
+      - "coreutils"
+      - "util-linux"
+      - "procps"
+      - "grep"
+      - "sed"
+      - "gawk"
+      - "findutils"
+      - "tar"
+      - "gzip"
+      - "bzip2"
+      - "xz-utils"
+      
+      # Network and security
+      - "ca-certificates"
+      - "openssl"
+      - "curl"
+      - "wget"
+      - "iproute2"
+      - "net-tools"
+      - "iptables"
+      
+      # Development tools (optional)
+      - "build-essential"
+      - "pkg-config"
+      - "git"
+      
+    exclude:
+      - "unwanted-package"
+      - "conflicting-package"
+      
+  # Customizations
+  customizations:
+    users:
+      - name: "admin"
+        groups: ["sudo", "docker"]
+        ssh_keys:
+          - "ssh-rsa AAAAB3NzaC1yc2EAAAADAQABAAABAQC..."
+    
+    files:
+      - path: "/etc/hostname"
+        content: "debian-atomic"
+        mode: "0644"
+        owner: "root:root"
+        
+      - path: "/etc/motd"
+        content: "Welcome to Debian Atomic (apt-ostree)"
+        mode: "0644"
+        owner: "root:root"
+        
+    services:
+      enable:
+        - "systemd-networkd"
+        - "systemd-resolved"
+        - "systemd-timesyncd"
+      disable:
+        - "unwanted-service"
+        
+  # OSTree configuration
+  ostree:
+    ref: "debian/trixie/amd64/base"
+    parent_ref: "debian/trixie/amd64/base"  # Optional
+    commit_message: "Debian Trixie base system with apt-ostree"
+    metadata:
+      build_tool: "deb-bootc-compose"
+      build_timestamp: "2025-08-19T18:44:29Z"
+      build_version: "1.0.0"
+    
+  # Build options
+  build:
+    parallel_jobs: 4
+    cache_dir: "/var/cache/apt-ostree"
+    cleanup: true