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
2025-08-19 11:55:41 -07:00 · 2025-08-19 11:55:41 -07:00 · cdc0251d4f
commit cdc0251d4f
parent 4b24e97960
3 changed files with 558 additions and 0 deletions
--- a/examples/README.md
+++ 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
--- a/examples/debian-trixie-base.yaml
+++ 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