# 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
```