debian-forge/docs/debian-image-building-tutorial.md

Debian Image Building Tutorial

This tutorial will guide you through building Debian images using debian-forge, a Debian-specific fork of OSBuild with full APT support.

Prerequisites

• debian-forge installed (see Installation Guide)
• Basic understanding of Debian package management
• Familiarity with JSON manifest format

Quick Start

1. Basic Debian Image

Let's start with a simple Debian Trixie minimal image:

{
  "version": "2",
  "pipelines": [
    {
      "runner": "org.osbuild.linux",
      "name": "build",
      "stages": [
        {
          "type": "org.osbuild.debootstrap",
          "options": {
            "suite": "trixie",
            "mirror": "http://deb.debian.org/debian",
            "arch": "amd64",
            "variant": "minbase"
          }
        },
        {
          "type": "org.osbuild.apt",
          "options": {
            "packages": ["linux-image-amd64", "systemd", "openssh-server"]
          }
        }
      ]
    }
  ]
}

Save this as debian-minimal.json and build it:

python3 -m osbuild debian-minimal.json --output-dir ./output --libdir .

2. Server Image with Custom Packages

For a server image, we'll add more packages and configuration:

{
  "version": "2",
  "pipelines": [
    {
      "runner": "org.osbuild.linux",
      "name": "build",
      "stages": [
        {
          "type": "org.osbuild.debootstrap",
          "options": {
            "suite": "trixie",
            "mirror": "http://deb.debian.org/debian",
            "arch": "amd64",
            "variant": "minbase",
            "extra_packages": ["apt", "systemd", "bash"]
          }
        },
        {
          "type": "org.osbuild.apt.config",
          "options": {
            "sources": {
              "debian": "deb http://deb.debian.org/debian trixie main\n"
            }
          }
        },
        {
          "type": "org.osbuild.apt",
          "options": {
            "packages": [
              "linux-image-amd64",
              "systemd",
              "openssh-server",
              "nginx",
              "mysql-server",
              "python3",
              "curl",
              "vim",
              "htop"
            ],
            "recommends": false,
            "update": true
          }
        },
        {
          "type": "org.osbuild.hostname",
          "options": {
            "hostname": "debian-server"
          }
        },
        {
          "type": "org.osbuild.systemd",
          "options": {
            "enabled_services": [
              "sshd",
              "systemd-networkd",
              "systemd-resolved",
              "nginx",
              "mysql"
            ]
          }
        }
      ]
    }
  ]
}

3. Ubuntu Image

Building Ubuntu images is similar, just change the suite and mirror:

{
  "version": "2",
  "pipelines": [
    {
      "runner": "org.osbuild.linux",
      "name": "build",
      "stages": [
        {
          "type": "org.osbuild.debootstrap",
          "options": {
            "suite": "jammy",
            "mirror": "http://archive.ubuntu.com/ubuntu",
            "arch": "amd64",
            "variant": "minbase"
          }
        },
        {
          "type": "org.osbuild.apt.config",
          "options": {
            "sources": {
              "ubuntu": "deb http://archive.ubuntu.com/ubuntu jammy main restricted universe multiverse\n"
            }
          }
        },
        {
          "type": "org.osbuild.apt",
          "options": {
            "packages": [
              "linux-image-generic",
              "systemd",
              "openssh-server",
              "curl",
              "vim"
            ]
          }
        }
      ]
    }
  ]
}

Advanced Features

Custom Repositories

Add custom repositories for additional packages:

{
  "type": "org.osbuild.apt.config",
  "options": {
    "sources": {
      "debian": "deb http://deb.debian.org/debian trixie main\n",
      "debian-forge": "deb https://git.raines.xyz/api/packages/particle-os/debian trixie main\n"
    }
  }
}

Package Preferences

Configure package pinning and preferences:

{
  "type": "org.osbuild.apt.config",
  "options": {
    "preferences": {
      "debian-forge": "Package: *\nPin: origin git.raines.xyz\nPin-Priority: 1000\n"
    }
  }
}

Cross-Architecture Builds

Build for different architectures:

{
  "type": "org.osbuild.debootstrap",
  "options": {
    "suite": "trixie",
    "mirror": "http://deb.debian.org/debian",
    "arch": "arm64",
    "variant": "minbase"
  }
}

APT Proxy

Use apt-cacher-ng for faster builds:

{
  "type": "org.osbuild.apt",
  "options": {
    "packages": ["linux-image-amd64"],
    "apt_proxy": "http://localhost:3142"
  }
}

Best Practices

1. Package Selection

• Use recommends: false to avoid installing unnecessary packages
• Include only essential packages in the base image
• Use extra_packages in debootstrap for core system packages

2. Repository Configuration

• Always configure APT sources explicitly
• Use HTTPS mirrors when available
• Consider using apt-cacher-ng for faster builds

3. Service Configuration

• Enable only necessary services
• Use systemd for service management
• Configure hostname and network settings

4. Security

• Keep packages updated
• Use minimal base images
• Configure firewall rules appropriately

Troubleshooting

Common Issues

1. Package not found: Check package name and availability
2. Repository errors: Verify mirror URL and suite name
3. Architecture issues: Ensure target architecture is supported
4. Network issues: Use apt-cacher-ng proxy

Debug Mode

Use the --break option to debug specific stages:

python3 -m osbuild manifest.json --break org.osbuild.apt

Logs

Check build logs for detailed information:

python3 -m osbuild manifest.json --json | jq '.log'

Examples

See the example manifests for more complete examples:

• debian-trixie-minimal.json - Minimal Debian Trixie image
• ubuntu-jammy-server.json - Ubuntu Jammy server image
• debian-atomic-container.json - Debian Atomic container image
• debian-trixie-arm64.json - ARM64 cross-architecture build

Next Steps

• APT Stages Reference
• Container Image Building
• Cloud Image Generation
• Performance Optimization