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](installation.md))
- 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:

```json
{
  "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:

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

```json
{
  "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:

```json
{
  "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:

```json
{
  "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:

```json
{
  "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:

```json
{
  "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:

```json
{
  "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:

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

### Logs

Check build logs for detailed information:

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

## Examples

See the [example manifests](../test/data/manifests/debian/) 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](apt-stages.md)
- [Container Image Building](container-image-building.md)
- [Cloud Image Generation](cloud-image-generation.md)
- [Performance Optimization](performance-optimization.md)