502e1469ae
Some checks failed
Checks / Spelling (push) Has been cancelled
Checks / Python Linters (push) Has been cancelled
Checks / Shell Linters (push) Has been cancelled
Checks / 📦 Packit config lint (push) Has been cancelled
Checks / 🔍 Check for valid snapshot urls (push) Has been cancelled
Checks / 🔍 Check JSON files for formatting consistency (push) Has been cancelled
Generate / Documentation (push) Has been cancelled
Generate / Test Data (push) Has been cancelled
Tests / Unittest (push) Has been cancelled
Tests / Assembler test (legacy) (push) Has been cancelled
Tests / Smoke run: unittest as normal user on default runner (push) Has been cancelled
117 lines
3.9 KiB
Markdown
Executable file
117 lines
3.9 KiB
Markdown
Executable file
# Debian Forge: debos to OSBuild Stage Mapping
|
|
|
|
## Overview
|
|
This document maps debos actions to OSBuild stages to enable Debian package management and OSTree composition in the OSBuild pipeline.
|
|
|
|
## Action Mappings
|
|
|
|
### Package Management
|
|
|
|
#### debos: `apt` → OSBuild: `org.osbuild.apt`
|
|
- **Purpose**: Install Debian packages using apt
|
|
- **Input**: Package list, repository configuration
|
|
- **Output**: Installed packages in target filesystem
|
|
- **Dependencies**: Repository configuration, package sources
|
|
|
|
#### debos: `debootstrap` → OSBuild: `org.osbuild.debootstrap`
|
|
- **Purpose**: Create base Debian filesystem
|
|
- **Input**: Debian suite, architecture, mirror
|
|
- **Output**: Base Debian root filesystem
|
|
- **Dependencies**: Network access, Debian mirror
|
|
|
|
### OSTree Integration
|
|
|
|
#### debos: `ostree-commit` → OSBuild: `org.osbuild.ostree.commit`
|
|
- **Purpose**: Create OSTree commit from filesystem
|
|
- **Input**: Filesystem tree, commit metadata
|
|
- **Output**: OSTree commit in repository
|
|
- **Dependencies**: OSTree repository, filesystem tree
|
|
|
|
#### debos: `ostree-deploy` → OSBuild: `org.osbuild.ostree.deploy`
|
|
- **Purpose**: Deploy OSTree branch to target
|
|
- **Input**: OSTree repository, branch name
|
|
- **Output**: Deployed OSTree filesystem
|
|
- **Dependencies**: OSTree repository, target device
|
|
|
|
### Filesystem Operations
|
|
|
|
#### debos: `overlay` → OSBuild: `org.osbuild.overlay`
|
|
- **Purpose**: Copy files/directories to target
|
|
- **Input**: Source files, target paths
|
|
- **Output**: Files copied to target filesystem
|
|
- **Dependencies**: Source files, target filesystem
|
|
|
|
#### debos: `filesystem-deploy` → OSBuild: `org.osbuild.filesystem.deploy`
|
|
- **Purpose**: Deploy filesystem to image
|
|
- **Input**: Filesystem tree, target image
|
|
- **Output**: Image with deployed filesystem
|
|
- **Dependencies**: Filesystem tree, target device
|
|
|
|
### Image Creation
|
|
|
|
#### debos: `image-partition` → OSBuild: `org.osbuild.image.partition`
|
|
- **Purpose**: Create and partition disk image
|
|
- **Input**: Partition layout, filesystem types
|
|
- **Output**: Partitioned disk image
|
|
- **Dependencies**: Partition specification
|
|
|
|
## Implementation Priority
|
|
|
|
### Phase 1: Core Package Management
|
|
1. **org.osbuild.apt** - Debian package installation
|
|
2. **org.osbuild.debootstrap** - Base filesystem creation
|
|
3. **org.osbuild.apt.repos** - Repository configuration
|
|
|
|
### Phase 2: OSTree Integration
|
|
1. **org.osbuild.ostree.commit** - Commit creation
|
|
2. **org.osbuild.ostree.deploy** - Deployment
|
|
3. **org.osbuild.ostree.repo** - Repository management
|
|
|
|
### Phase 3: Advanced Features
|
|
1. **org.osbuild.overlay** - File operations
|
|
2. **org.osbuild.filesystem.deploy** - Filesystem deployment
|
|
3. **org.osbuild.image.partition** - Image creation
|
|
|
|
## Stage Structure
|
|
|
|
Each OSBuild stage should follow the standard pattern:
|
|
- Python script for the stage logic
|
|
- JSON metadata file defining options and dependencies
|
|
- Integration with OSBuild pipeline system
|
|
- Proper error handling and logging
|
|
|
|
## Dependencies
|
|
|
|
- **Python 3.6+** for stage execution
|
|
- **apt/dpkg** for Debian package management
|
|
- **ostree** for atomic filesystem management
|
|
- **debootstrap** for base filesystem creation
|
|
- **sbuild/pbuilder** for build environments
|
|
- **apt-cacher-ng** for package caching (optional, improves performance)
|
|
|
|
## apt-cacher-ng Integration
|
|
|
|
### Configuration
|
|
Both `org.osbuild.apt` and `org.osbuild.debootstrap` stages support apt-cacher-ng proxy configuration:
|
|
|
|
```json
|
|
{
|
|
"name": "org.osbuild.apt",
|
|
"options": {
|
|
"packages": ["systemd", "dbus"],
|
|
"apt_proxy": "http://localhost:3142"
|
|
}
|
|
}
|
|
```
|
|
|
|
### Benefits
|
|
- **Faster builds** - Packages are cached locally
|
|
- **Reduced network usage** - Avoids re-downloading packages
|
|
- **Offline capability** - Can build without internet after initial cache
|
|
- **Development efficiency** - Faster iteration during development
|
|
|
|
### Setup
|
|
Use the provided `setup-apt-cacher.sh` script to configure apt-cacher-ng:
|
|
```bash
|
|
sudo ./debian-forge/setup-apt-cacher.sh
|
|
```
|