robojerk
cdc0251d4f
- 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
354 lines
8.2 KiB
Markdown
354 lines
8.2 KiB
Markdown
# 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.
|