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

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

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

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

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

```bash
$ 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:

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

```bash
# 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)
```bash
$ ./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
```bash
$ ./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
```bash
$ ./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
```bash
$ ./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
```bash
❌ Failed to create runner: [Errno 13] Permission denied
```

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

### Distribution Not Detected
```bash
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:

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

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