particle-os/apt-ostree
1
0
Fork 0
Code Issues 1 Pull requests Projects Releases Packages Wiki Activity Actions

docs: create comprehensive integration howto for external tools

Browse source 
- 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
This commit is contained in:
robojerk 2025-08-19 11:55:41 -07:00
parent 4b24e97960
commit cdc0251d4f
3 changed files with 558 additions and 0 deletions
Download patch file Download diff file Expand all files Collapse all files

354
docs/INTEGRATION_HOWTO.md Normal file
View file

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

106
examples/README.md Normal file
View file

@ -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

98
examples/debian-trixie-base.yaml Normal file
View file

@ -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