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
106 lines
2.4 KiB
Markdown
106 lines
2.4 KiB
Markdown
# 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
|