deb-bootc-compose/README.md

# deb-bootc-compose

**Debian's equivalent to Fedora's Pungi compose system**

`deb-bootc-compose` is a Debian-native composition tool that orchestrates the creation of Debian bootc images from packages. It coordinates the entire compose process, similar to how Pungi coordinates Fedora's release process.

## What It Does

`deb-bootc-compose` serves as the **main orchestrator** for Debian's bootc ecosystem:

- **Package Coordination**: Ensures all release artifacts use identical package versions across variants
- **Multi-Artifact Generation**: Creates container images, disk images, and other bootc artifacts
- **Build Orchestration**: Coordinates with `deb-orchestrator` (Koji equivalent) and `deb-mock` (Mock equivalent)
- **OSTree Integration**: Orchestrates bootc image creation through apt-ostree
- **Variant Management**: Handles different Debian variants (minimal, server, desktop, etc.)

## Architecture

The tool follows a **phase-based architecture** inspired by Pungi:

```
┌─────────────────┐    ┌─────────────────┐    ┌─────────────────┐
│ deb-bootc-      │    │ deb-orchestrator│    │    deb-mock     │
│   compose       │    │   (Koji equiv)  │    │   (Mock equiv)  │
│ Orchestrator    │    │ Build System    │    │Build Environment│
└─────────────────┘    └─────────────────┘    └─────────────────┘
         │                       │                       │
         │ Coordinates           │ Manages               │ Creates
         │ entire process        │ package building      │ isolated
         │                       │ at scale              │ environments
```

### Core Phases

1. **init**: Initialize compose environment
2. **gather**: Download and organize packages
3. **build**: Build packages if needed
4. **ostree**: Create OSTree commits
5. **output**: Generate output artifacts
6. **cleanup**: Clean up temporary files

## Quick Start

### Prerequisites

- Go 1.21 or later
- Debian-based system (for development)
- Basic understanding of Debian packaging

### Installation

```bash
# Clone the repository
git clone https://github.com/debian/deb-bootc-compose.git
cd deb-bootc-compose

# Install dependencies
make deps

# Build the binary
make build

# Run with help
./build/deb-bootc-compose --help
```

### Basic Usage

```bash
# Run a compose with a treefile
./build/deb-bootc-compose \
    --treefile examples/debian-bootc-minimal.json \
    --output ./compose-output \
    --config configs/compose.yaml
```

## Configuration

### Compose Configuration

The main configuration file (`compose.yaml`) controls:

- **Compose settings**: Release, variants, architectures
- **Build system**: sbuild, debootstrap integration
- **OSTree settings**: Repository mode, signing
- **Output formats**: Container, disk image, chunked OCI
- **Integration**: deb-orchestrator connection settings

### Treefiles

Treefiles (JSON manifests) define what gets built:

- **Package lists**: Required, optional, recommended packages
- **Variants**: Different flavors (minimal, server, desktop)
- **Architectures**: Target CPU architectures
- **Repositories**: Package sources
- **Build settings**: Build system configuration

Example treefile structure:
```json
{
  "name": "debian-bootc-minimal",
  "version": "13",
  "release": "bookworm",
  "packages": {
    "required": ["linux-image-amd64", "systemd", "ostree", "bootc"]
  },
  "architecture": ["amd64", "arm64"],
  "variants": [
    {
      "name": "minimal",
      "description": "Minimal base system"
    }
  ]
}
```

## Development

### Project Structure

```
deb-bootc-compose/
├── cmd/                    # Command-line interfaces
│   ├── compose/           # Main compose command
│   └── cli/              # CLI utilities
├── internal/              # Internal packages
│   ├── compose/           # Core compose engine
│   ├── config/            # Configuration management
│   ├── ostree/            # OSTree integration
│   └── build/             # Build system interface
├── pkg/                   # Public packages
├── configs/               # Configuration files
├── examples/              # Example treefiles
└── docs/                  # Documentation
```

### Building

```bash
# Build everything
make all

# Build specific components
make build      # Main binary
make cli        # CLI tool

# Development helpers
make test       # Run tests
make fmt        # Format code
make lint       # Lint code
make clean      # Clean build artifacts
```

### Testing

```bash
# Run all tests
make test

# Run tests with coverage
make test-coverage

# Run with sample treefile
make run-sample
```

## Integration

### With deb-orchestrator

`deb-bootc-compose` integrates with `deb-orchestrator` for:

- **Package management**: Downloading packages from build system
- **Build coordination**: Ensuring package availability before compose
- **Metadata integration**: Using build metadata for versioning

### With deb-mock

`deb-bootc-compose` can use `deb-mock` for:

- **Build environment creation**: Isolated chroot environments
- **Package installation**: Installing build dependencies
- **Environment isolation**: Reproducible builds

## Status

**Current Status**: Phase 1 - Foundation Development

- ✅ **Core engine**: Basic compose engine implemented
- ✅ **Treefile parser**: JSON-based configuration system
- ✅ **Phase management**: Simple phase execution system
- ✅ **Configuration**: YAML-based configuration system
- 🔄 **OSTree integration**: Placeholder implementation
- 🔄 **Build system**: Placeholder implementation
- ❌ **Integration**: Not yet integrated with other tools

## Roadmap

See the main project [TODO.md](../TODO.md) for the complete development roadmap.

### Phase 1 (Months 1-6): Foundation
- Core compose engine working
- Basic treefile parsing and validation
- OSTree integration functional
- Container output working

### Phase 2 (Months 7-10): Integration
- Deep integration with deb-orchestrator and deb-mock
- Advanced features and optimization
- Production readiness features

### Phase 3 (Months 11-14): Production
- Security audit and hardening
- Performance optimization
- Community integration

### Phase 4 (Months 15-18): Ecosystem
- Debian Atomic and Particle-OS variants
- Advanced use cases
- Community adoption

## Contributing

We welcome contributions! Please see our [Contributing Guide](CONTRIBUTING.md) for details.

### Development Setup

```bash
# Set up development environment
make dev-setup

# Install development tools
go install github.com/golangci/golangci-lint/cmd/golangci-lint@latest
```

## License

This project is licensed under the same terms as Debian (GPL-2+).

## Related Projects

- **deb-orchestrator**: Debian's equivalent to Fedora's Koji build system
- **deb-mock**: Debian's equivalent to Fedora's Mock build environment manager
- **deb-bootc-compose**: This project - the main orchestrator

## Support

- **Issues**: [GitHub Issues](https://github.com/debian/deb-bootc-compose/issues)
- **Discussions**: [GitHub Discussions](https://github.com/debian/deb-bootc-compose/discussions)
- **Documentation**: [Project Wiki](https://github.com/debian/deb-bootc-compose/wiki)

---

**Part of Debian's complete bootc ecosystem** - building Debian's answer to Fedora's Pungi-Koji-Mock ecosystem.