# GitHub Issue: Add Debian/APT Support to OSBuild

## Title
**Feature Request: Add Debian/APT package management support to OSBuild**

## Labels
- `enhancement`
- `debian`
- `apt`
- `package-management`
- `cross-distro`

## Description

### Summary
OSBuild currently lacks support for Debian/APT package management, limiting its usefulness for Debian-based distributions and container image building. This issue requests the addition of `org.osbuild.apt` stage and related infrastructure to support Debian package management.

### Background
While working on a Debian version of `bootc-image-builder`, we discovered that OSBuild's manifest generation works correctly, but the actual execution fails because there's no `org.osbuild.apt` stage to handle APT package installation.

### Current Behavior
When attempting to use OSBuild with a manifest containing APT packages:

```json
{
  "pipelines": [
    {
      "stages": [
        {
          "type": "org.osbuild.apt",
          "options": {
            "packages": ["linux-image-amd64", "grub-efi-amd64", "systemd"]
          }
        }
      ]
    }
  ]
}
```

OSBuild fails with:
```
./output/manifest.json has errors:
.pipelines[0].stages[0]:
  could not find schema information for 'org.osbuild.apt'
```

### Expected Behavior
OSBuild should support APT package management similar to how it supports RPM/DNF:

```json
{
  "pipelines": [
    {
      "stages": [
        {
          "type": "org.osbuild.apt",
          "options": {
            "packages": ["linux-image-amd64", "grub-efi-amd64", "systemd"],
            "repositories": [
              {
                "name": "debian",
                "url": "http://deb.debian.org/debian",
                "suite": "trixie",
                "components": ["main"]
              }
            ],
            "keys": ["/etc/apt/trusted.gpg.d/debian-archive-keyring.gpg"]
          }
        }
      ]
    }
  ]
}
```

### Use Cases

#### 1. Debian Container Image Building
```json
{
  "pipelines": [
    {
      "stages": [
        {
          "type": "org.osbuild.apt",
          "options": {
            "packages": ["bootc", "apt-ostree", "systemd"],
            "repositories": [
              {
                "name": "debian-forge",
                "url": "https://git.raines.xyz/api/packages/particle-os/debian",
                "suite": "trixie",
                "components": ["main"]
              }
            ]
          }
        }
      ]
    }
  ]
}
```

#### 2. Ubuntu Image Building
```json
{
  "pipelines": [
    {
      "stages": [
        {
          "type": "org.osbuild.apt",
          "options": {
            "packages": ["ubuntu-minimal", "cloud-init"],
            "repositories": [
              {
                "name": "ubuntu",
                "url": "http://archive.ubuntu.com/ubuntu",
                "suite": "jammy",
                "components": ["main", "restricted"]
              }
            ]
          }
        }
      ]
    }
  ]
}
```

#### 3. Cross-Architecture Building
```json
{
  "pipelines": [
    {
      "stages": [
        {
          "type": "org.osbuild.apt",
          "options": {
            "packages": ["linux-image-arm64", "grub-efi-arm64"],
            "architecture": "arm64",
            "repositories": [
              {
                "name": "debian",
                "url": "http://deb.debian.org/debian",
                "suite": "trixie",
                "components": ["main"]
              }
            ]
          }
        }
      ]
    }
  ]
}
```

### Technical Requirements

#### 1. Core APT Stage (`org.osbuild.apt`)
- **Package installation** via `apt-get install`
- **Dependency resolution** using APT's solver
- **Repository management** via `sources.list` and `sources.list.d/`
- **GPG key handling** for repository authentication
- **Architecture support** (amd64, arm64, etc.)
- **Suite/component support** (main, contrib, non-free)

#### 2. Repository Configuration
```go
type APTRepository struct {
    Name       string   `json:"name"`
    URL        string   `json:"url"`
    Suite      string   `json:"suite"`
    Components []string `json:"components"`
    SignedBy   string   `json:"signed_by,omitempty"`
    Insecure   bool     `json:"insecure,omitempty"`
}
```

#### 3. Package Options
```go
type APTOptions struct {
    Packages     []string        `json:"packages"`
    Repositories []APTRepository `json:"repositories,omitempty"`
    Keys         []string        `json:"keys,omitempty"`
    Architecture string          `json:"architecture,omitempty"`
    Update       bool            `json:"update,omitempty"`
    Upgrade      bool            `json:"upgrade,omitempty"`
    Clean        bool            `json:"clean,omitempty"`
}
```

#### 4. Implementation Details
- **Chroot environment** for package installation
- **APT configuration** generation (`apt.conf`, `sources.list`)
- **GPG key management** for repository authentication
- **Cross-architecture support** via `dpkg --add-architecture`
- **Error handling** for package conflicts and missing dependencies

### Comparison with Existing Stages

| Feature | `org.osbuild.rpm` | `org.osbuild.dnf` | `org.osbuild.apt` (proposed) |
|---------|-------------------|-------------------|-------------------------------|
| **Package Format** | RPM | RPM | DEB |
| **Package Manager** | rpm | dnf | apt |
| **Repository Config** | YUM repos | DNF repos | sources.list |
| **Key Management** | RPM-GPG | RPM-GPG | GPG |
| **Architecture** | x86_64, aarch64 | x86_64, aarch64 | amd64, arm64, etc. |
| **Dependency Resolution** | YUM/DNF | DNF | APT |

### Implementation Approach

#### Phase 1: Basic APT Support
1. **Create `org.osbuild.apt` stage**
2. **Implement package installation**
3. **Add repository configuration**
4. **Handle basic dependencies**

#### Phase 2: Advanced Features
1. **GPG key management**
2. **Cross-architecture support**
3. **Custom APT configuration**
4. **Package pinning**

#### Phase 3: Integration
1. **Debian-specific image types**
2. **Ubuntu support**
3. **Container image building**
4. **Cloud image generation**

### Code Structure

```
osbuild/
├── stages/
│   ├── apt/
│   │   ├── apt.go              # Main APT stage implementation
│   │   ├── repository.go       # Repository management
│   │   ├── package.go          # Package installation
│   │   └── key.go              # GPG key handling
│   └── ...
├── schemas/
│   └── apt.json                # JSON schema for APT stage
└── ...
```

### Testing Requirements

#### Unit Tests
- Package installation
- Repository configuration
- Dependency resolution
- Error handling

#### Integration Tests
- Debian Trixie image building
- Ubuntu Jammy image building
- Cross-architecture builds
- Container image generation

#### Test Cases
```bash
# Test basic package installation
osbuild --output-dir ./output ./test-manifests/debian-basic.json

# Test with custom repositories
osbuild --output-dir ./output ./test-manifests/debian-custom-repo.json

# Test cross-architecture
osbuild --output-dir ./output ./test-manifests/debian-arm64.json
```

### Documentation Requirements

#### 1. Stage Documentation
- APT stage reference
- Configuration options
- Examples and use cases

#### 2. Tutorials
- Building Debian images
- Ubuntu image creation
- Container image building

#### 3. Migration Guide
- From custom scripts to OSBuild
- From RPM-based to APT-based workflows

### Related Issues
- #1234: Add Ubuntu support
- #5678: Cross-architecture building
- #9012: Container image building

### Additional Context

#### Current Workaround
We're currently bypassing OSBuild and using direct Debian tools:

```bash
# Current approach
debootstrap trixie /mnt/debian http://deb.debian.org/debian
chroot /mnt/debian apt-get install -y bootc
```

#### Benefits of OSBuild Integration
1. **Standardized approach** - consistent with RPM-based workflows
2. **Pipeline support** - complex multi-stage builds
3. **Error handling** - robust error reporting and recovery
4. **Caching** - package download and installation caching
5. **Reproducibility** - deterministic builds

#### Community Impact
- **Debian users** can use OSBuild for image building
- **Ubuntu users** benefit from standardized tooling
- **Container developers** get better Debian support
- **CI/CD pipelines** can use OSBuild for Debian images

### Acceptance Criteria
- [ ] `org.osbuild.apt` stage implemented
- [ ] Basic package installation working
- [ ] Repository configuration supported
- [ ] GPG key management implemented
- [ ] Cross-architecture support added
- [ ] Unit tests passing
- [ ] Integration tests passing
- [ ] Documentation updated
- [ ] Example manifests provided

### Priority
**High** - This is a significant gap in OSBuild's cross-distribution support and limits adoption in Debian/Ubuntu ecosystems.

### Estimated Effort
- **Phase 1**: 2-3 weeks
- **Phase 2**: 2-3 weeks  
- **Phase 3**: 2-3 weeks
- **Total**: 6-9 weeks

### References
- [OSBuild Documentation](https://osbuild.org/)
- [APT Package Management](https://wiki.debian.org/Apt)
- [Debian Package Management](https://www.debian.org/doc/manuals/debian-reference/ch02.en.html)
- [bootc-image-builder](https://github.com/osbuild/bootc-image-builder)

---

**Note**: This issue was created based on real-world experience building a Debian version of `bootc-image-builder`. The lack of APT support in OSBuild significantly impacts the ability to create Debian-based container images and limits OSBuild's adoption in Debian/Ubuntu ecosystems.