docs: create comprehensive integration howto for external tools
Some checks failed
Comprehensive CI/CD Pipeline / Build and Test (push) Successful in 8m6s
Comprehensive CI/CD Pipeline / Security Audit (push) Failing after 7s
Comprehensive CI/CD Pipeline / Package Validation (push) Successful in 2m21s
Comprehensive CI/CD Pipeline / Status Report (push) Has been skipped
Some checks failed
Comprehensive CI/CD Pipeline / Build and Test (push) Successful in 8m6s
Comprehensive CI/CD Pipeline / Security Audit (push) Failing after 7s
Comprehensive CI/CD Pipeline / Package Validation (push) Successful in 2m21s
Comprehensive CI/CD Pipeline / Status Report (push) Has been skipped
- 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:
parent
be6db709ae
commit
15b981d38f
3 changed files with 558 additions and 0 deletions
354
docs/INTEGRATION_HOWTO.md
Normal file
354
docs/INTEGRATION_HOWTO.md
Normal 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
106
examples/README.md
Normal 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
98
examples/debian-trixie-base.yaml
Normal 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
|
||||
Loading…
Add table
Add a link
Reference in a new issue