# 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