346 lines
9.4 KiB
Markdown
346 lines
9.4 KiB
Markdown
# 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.
|