debian-forge/docs/debian-runners.md

Debian Runner System

This document explains how Debian Forge implements a dynamic runner system similar to Fedora OSBuild, automatically detecting and using the appropriate runner for different Debian-based distributions.

Overview

Just like Fedora OSBuild automatically detects and uses the right runner for different Fedora versions, Debian Forge now provides the same functionality for Debian-based distributions.

How It Works

1. Automatic Detection

The system automatically detects your distribution and creates a symbolic link to the appropriate runner:

# Fedora-style automatic detection
$ ls -la runners/
org.osbuild.fedora38*    # Fedora 38 runner
org.osbuild.fedora39*    # Fedora 39 runner  
org.osbuild.fedora40*    # Fedora 40 runner
org.osbuild.fedora41*    # Fedora 41 runner
org.osbuild.linux*       # Generic Linux runner

# Debian Forge equivalent
$ ls -la runners/
org.osbuild.debian13*    # Debian 13 (Trixie) runner
org.osbuild.debian14*    # Debian 14 (Forky) runner
org.osbuild.ubuntu2504*  # Ubuntu 25.04 (Plucky Puffin) runner
org.osbuild.ubuntu2404*  # Ubuntu 24.04 (Noble Numbat) runner
org.osbuild.debian-based* # Generic Debian-based runner
org.osbuild.linux*       # Generic Linux runner

2. Dynamic Runner Mapping

When you run OSBuild, it automatically uses the runner that matches your system:

# On Debian Trixie (13)
$ python3 -m osbuild --libdir . manifest.json
# Automatically uses org.osbuild.debian13

# On Ubuntu 25.04
$ python3 -m osbuild --libdir . manifest.json  
# Automatically uses org.osbuild.ubuntu2504

# On your current system (bazzite)
$ python3 -m osbuild --libdir . manifest.json
# Automatically uses org.osbuild.bazzite -> org.osbuild.linux

Available Runners

🐧 Debian Runners

Runner	Distribution	Version	Status	Description
org.osbuild.debian13	Debian	13 (Trixie)	STABLE	Production-ready Debian 13
org.osbuild.debian14	Debian	14 (Forky)	TESTING	Development/testing Debian 14
org.osbuild.debian-sid	Debian	Sid	UNSTABLE	Unstable development (use with caution)
org.osbuild.debian	Debian	Generic	LEGACY	Generic Debian runner
org.osbuild.debian-based	Debian-based	Generic	GENERIC	Other Debian derivatives

🦊 Ubuntu Runners

Runner	Distribution	Version	Codename	Status
org.osbuild.ubuntu2504	Ubuntu	25.04	Plucky Puffin	LTS
org.osbuild.ubuntu2404	Ubuntu	24.04	Noble Numbat	LTS
org.osbuild.ubuntu1804	Ubuntu	18.04	Bionic Beaver	LTS

🔧 Other Runners

Runner	Distribution	Type
org.osbuild.linux	Generic Linux	FALLBACK
org.osbuild.fedora*	Fedora variants	EXISTING
org.osbuild.rhel*	RHEL variants	EXISTING

Runner Features

Debian-Specific Optimizations

Each Debian runner includes:

• Environment Variables: DEBIAN_FRONTEND=noninteractive
• Package Management: Automatic apt-get update
• Sources Backup: Automatic backup of /etc/apt/sources.list
• Distribution Detection: Automatic codename/version detection

Ubuntu-Specific Optimizations

Each Ubuntu runner includes:

• Environment Variables: Ubuntu-specific settings
• LTS Detection: Automatic LTS release detection
• Package Management: Ubuntu-optimized apt configuration
• Version Mapping: Automatic version-to-codename mapping

Generic Debian-Based Runner

The org.osbuild.debian-based runner automatically detects:

• Linux Mint
• Pop!_OS
• Elementary OS
• Zorin OS
• Kali Linux
• Parrot OS
• Other Debian derivatives

Setup and Usage

1. Automatic Setup

The system automatically sets up the right runner for your system:

# Automatic detection and setup
$ ./tools/debian-runner-setup

🔍 Debian Runner Setup Tool
========================================
Distribution: unknown
Version: unknown
Codename: unknown
Recommended runner: org.osbuild.linux

✅ Created runner: org.osbuild.bazzite -> org.osbuild.linux

🎯 Runner setup complete!
   Your system 'bazzite' now uses org.osbuild.linux
   OSBuild will automatically use the appropriate runner for your system

2. Manual Runner Selection

You can manually select a specific runner:

# List available runners
$ ./tools/debian-runner-setup list

# Create a specific runner
$ ln -sf org.osbuild.debian13 runners/org.osbuild.mysystem

3. Runner Verification

Check which runner your system is using:

$ ls -la runners/org.osbuild.$(hostname)
lrwxrwxrwx. 1 user user 17 Aug 26 16:11 org.osbuild.bazzite -> org.osbuild.linux

Configuration

Environment Variables

Each runner sets appropriate environment variables:

# Debian runners
DEBIAN_FRONTEND=noninteractive
DEBCONF_NONINTERACTIVE_SEEN=true
DEBIAN_TESTING=1          # For testing releases
DEBIAN_UNSTABLE=1         # For unstable releases

# Ubuntu runners  
DEBIAN_FRONTEND=noninteractive
DEBCONF_NONINTERACTIVE_SEEN=true
UBUNTU_CODENAME=plucky
UBUNTU_VERSION=25.04
UBUNTU_LTS=1

Package Sources

Runners automatically configure appropriate package sources:

# Debian 13 (Trixie)
deb http://deb.debian.org/debian trixie main
deb http://deb.debian.org/debian trixie-updates main
deb http://deb.debian.org/debian trixie-security main
deb http://deb.debian.org/debian trixie-backports main

# Ubuntu 25.04 (Plucky Puffin)
deb http://archive.ubuntu.com/ubuntu plucky main
deb http://archive.ubuntu.com/ubuntu plucky-updates main
deb http://security.ubuntu.com/ubuntu plucky-security main

Benefits

✅ No Hardcoded Versions

• Before: Hardcoded bookworm everywhere
• After: Automatically detects and uses appropriate version

✅ Cross-Distribution Support

• Debian: Trixie, Forky, Sid, and future releases
• Ubuntu: 24.04, 25.04, and future LTS releases
• Other: Linux Mint, Pop!_OS, Elementary OS, etc.

✅ Future-Proof

• New releases: Automatically supported
• Version upgrades: No code changes needed
• Distribution changes: Automatic detection

✅ Fedora-Style Workflow

• Automatic detection: Like dnf detecting Fedora version
• Smart defaults: Like OSBuild choosing the right runner
• Graceful fallbacks: Like falling back to generic Linux runner

Examples

On Debian Trixie (13)

$ ./tools/debian-runner-setup
Distribution: debian
Codename: trixie
Recommended runner: org.osbuild.debian13

✅ Created runner: org.osbuild.trixie -> org.osbuild.debian13

On Ubuntu 25.04

$ ./tools/debian-runner-setup
Distribution: ubuntu
Version: 25.04
Recommended runner: org.osbuild.ubuntu2504

✅ Created runner: org.osbuild.plucky -> org.osbuild.ubuntu2504

On Linux Mint

$ ./tools/debian-runner-setup
Distribution: debian-based
Recommended runner: org.osbuild.debian-based

✅ Created runner: org.osbuild.mint -> org.osbuild.debian-based

Troubleshooting

Runner Not Found

$ ./tools/debian-runner-setup
❌ Recommended runner org.osbuild.debian13 not found!
   Available runners:
   - org.osbuild.debian
   - org.osbuild.linux
   - org.osbuild.ubuntu1804

Solution: Use ./tools/debian-runner-setup list to see available runners and manually create the link.

Permission Denied

❌ Failed to create runner: [Errno 13] Permission denied

Solution: Ensure you have write permissions to the runners/ directory.

Distribution Not Detected

Distribution: unknown
Recommended runner: org.osbuild.linux

Solution: The system falls back to the generic Linux runner, which should work for most cases.

Integration with OSBuild

Automatic Runner Selection

OSBuild automatically selects the appropriate runner based on your system:

# OSBuild automatically finds the right runner
runner = osbuild.find_runner()  # Returns org.osbuild.debian13 on Debian Trixie

Runner Priority

OSBuild uses this priority order for runner selection:

1. System-specific runner (e.g., org.osbuild.bazzite)
2. Distribution-specific runner (e.g., org.osbuild.debian13)
3. Generic runner (e.g., org.osbuild.linux)

Fallback Behavior

If no specific runner is found, the system gracefully falls back:

# No specific runner found
$ python3 -m osbuild --libdir . manifest.json
# Automatically uses org.osbuild.linux
# No errors, just generic Linux behavior

Future Enhancements

Planned Features

• Automatic runner updates: Update runners when new distributions are detected
• Custom runner creation: Allow users to create custom runners
• Runner validation: Validate runner compatibility with current system
• Performance optimization: Optimize runners for specific distributions

Distribution Support

• Debian: All future releases (15, 16, etc.)
• Ubuntu: All future LTS releases (26.04, 28.04, etc.)
• Other: More Debian derivatives (MX Linux, SparkyLinux, etc.)

Conclusion

The Debian runner system provides the same level of automation and intelligence as Fedora OSBuild, automatically detecting your distribution and using the appropriate runner. This eliminates the need for hardcoded versions and provides a seamless, future-proof experience across all Debian-based distributions.

Key Benefits:

• 🚀 Automatic detection like Fedora
• 🔄 Future-proof for new releases
• 🎯 Distribution-specific optimizations
• ⚡ Zero configuration required
• 🛡️ Graceful fallbacks for compatibility