Complete documentation updates: architecture, user guide, deployment, troubleshooting

debian-forge-docs/debos-osbuild-mapping.md

@@ -0,0 +1,117 @@
+# 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 filesystems
+- **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
+```