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