debian-forge/debian-forge-docs/debian-atomic-blueprints.md

Debian Atomic Blueprints for OSBuild Composer

Overview

This document defines the blueprint system for creating Debian atomic images using OSBuild Composer. The blueprints are based on debos recipe patterns and adapted for OSBuild's pipeline-based architecture.

Blueprint Structure

Basic Debian Atomic Blueprint

{
  "name": "debian-atomic-base",
  "description": "Debian Atomic Base System",
  "version": "0.0.1",
  "packages": [
    {"name": "systemd"},
    {"name": "systemd-sysv"},
    {"name": "dbus"},
    {"name": "udev"},
    {"name": "ostree"},
    {"name": "linux-image-amd64"}
  ],
  "modules": [],
  "groups": [],
  "customizations": {
    "user": [
      {
        "name": "debian",
        "description": "Debian user",
        "password": "$6$rounds=656000$YQvKxqQKqQKqQKqQ$...",
        "key": "ssh-rsa AAAAB3NzaC1yc2EAAAADAQABAAABAQC...",
        "home": "/home/debian",
        "shell": "/bin/bash",
        "groups": ["wheel"],
        "uid": 1000,
        "gid": 1000
      }
    ],
    "services": {
      "enabled": ["sshd", "systemd-networkd"]
    }
  }
}

Debian Atomic Workstation Blueprint

{
  "name": "debian-atomic-workstation",
  "description": "Debian Atomic Workstation",
  "version": "0.0.1",
  "packages": [
    {"name": "systemd"},
    {"name": "systemd-sysv"},
    {"name": "dbus"},
    {"name": "udev"},
    {"name": "ostree"},
    {"name": "linux-image-amd64"},
    {"name": "gnome-shell"},
    {"name": "gnome-session"},
    {"name": "gdm3"},
    {"name": "network-manager"},
    {"name": "firefox-esr"}
  ],
  "modules": [],
  "groups": [
    {"name": "desktop"}
  ],
  "customizations": {
    "user": [
      {
        "name": "debian",
        "description": "Debian user",
        "password": "$6$rounds=656000$YQvKxqQKqQKqQKqQ$...",
        "key": "ssh-rsa AAAAB3NzaC1yc2EAAAADAQABAAABAQC...",
        "home": "/home/debian",
        "shell": "/bin/bash",
        "groups": ["wheel", "desktop"],
        "uid": 1000,
        "gid": 1000
      }
    ],
    "services": {
      "enabled": ["sshd", "systemd-networkd", "gdm3", "NetworkManager"]
    },
    "desktop": {
      "enabled": true
    }
  }
}

Debian Atomic Server Blueprint

{
  "name": "debian-atomic-server",
  "description": "Debian Atomic Server",
  "version": "0.0.1",
  "packages": [
    {"name": "systemd"},
    {"name": "systemd-sysv"},
    {"name": "dbus"},
    {"name": "udev"},
    {"name": "ostree"},
    {"name": "linux-image-amd64"},
    {"name": "nginx"},
    {"name": "postgresql"},
    {"name": "redis-server"},
    {"name": "fail2ban"}
  ],
  "modules": [],
  "groups": [
    {"name": "server"}
  ],
  "customizations": {
    "user": [
      {
        "name": "debian",
        "description": "Debian user",
        "password": "$6$rounds=656000$YQvKxqQKqQKqQKqQ$...",
        "key": "ssh-rsa AAAAB3NzaC1yc2EAAAADAQABAAABAQC...",
        "home": "/home/debian",
        "shell": "/bin/bash",
        "groups": ["wheel", "server"],
        "uid": 1000,
        "gid": 1000
      }
    ],
    "services": {
      "enabled": ["sshd", "systemd-networkd", "nginx", "postgresql", "redis-server", "fail2ban"]
    },
    "firewall": {
      "services": {
        "enabled": ["ssh", "http", "https"]
      }
    }
  }
}

Blueprint Variables

Architecture Support

{
  "variables": {
    "architecture": "amd64",
    "suite": "bookworm",
    "variant": "minbase",
    "mirror": "http://deb.debian.org/debian",
    "apt_proxy": "http://192.168.1.101:3142"
  }
}

Package Categories

{
  "package_groups": {
    "base": ["systemd", "systemd-sysv", "dbus", "udev", "ostree"],
    "desktop": ["gnome-shell", "gnome-session", "gdm3"],
    "server": ["nginx", "postgresql", "redis-server"],
    "development": ["build-essential", "git", "python3", "nodejs"],
    "security": ["fail2ban", "unattended-upgrades", "rkhunter"]
  }
}

OSBuild Pipeline Integration

Debian Bootstrap Stage

{
  "type": "org.osbuild.debootstrap",
  "options": {
    "suite": "bookworm",
    "mirror": "http://deb.debian.org/debian",
    "arch": "amd64",
    "variant": "minbase",
    "apt_proxy": "http://192.168.1.101:3142"
  }
}

Package Installation Stage

{
  "type": "org.osbuild.apt",
  "options": {
    "packages": ["systemd", "systemd-sysv", "dbus", "udev"],
    "recommends": false,
    "update": true,
    "apt_proxy": "http://192.168.1.101:3142"
  }
}

OSTree Commit Stage

{
  "type": "org.osbuild.ostree.commit",
  "options": {
    "repo": "debian-atomic",
    "branch": "debian/bookworm",
    "subject": "Debian Bookworm atomic system",
    "body": "Debian Bookworm minbase system with systemd and OSTree"
  }
}

Blueprint Validation

Required Fields

• name: Unique identifier for the blueprint
• description: Human-readable description
• version: Semantic version string
• packages: Array of package specifications

Optional Fields

• modules: Debian modules (currently empty for atomic)
• groups: Package groups
• customizations: User, service, and system customizations
• variables: Blueprint variables for templating

Usage Examples

Creating a Blueprint

# Submit blueprint to composer
composer-cli blueprints push debian-atomic-base.json

# List available blueprints
composer-cli blueprints list

# Show blueprint details
composer-cli blueprints show debian-atomic-base

Building an Image

# Start a compose
composer-cli compose start debian-atomic-base qcow2

# Check compose status
composer-cli compose status

# Download the image
composer-cli compose image <compose-id>

Integration with Debian Forge

Build Orchestration

The blueprints integrate with our build orchestration system:

1. Blueprint Submission: User submits blueprint via composer API
2. Pipeline Generation: Composer generates OSBuild pipeline from blueprint
3. Build Execution: Our build orchestrator executes the pipeline
4. OSTree Composition: Debian stages create atomic filesystem
5. Image Generation: Output formats (ISO, QCOW2, RAW) generated
6. Deployment: OSTree commits available for deployment

Customization Points

• Package Selection: Via blueprint packages array
• User Configuration: Via blueprint customizations
• Service Management: Via blueprint services
• Security Settings: Via blueprint security groups
• Network Configuration: Via blueprint network settings

Future Enhancements

Advanced Blueprint Features

• Template Inheritance: Base blueprints with specialization
• Conditional Packages: Architecture or suite-specific packages
• Repository Management: Custom Debian repositories
• Security Policies: SELinux, AppArmor, and security modules
• Compliance: FIPS, Common Criteria, and security certifications

Integration Features

• CI/CD Integration: GitOps workflow integration
• Multi-Architecture: ARM64, RISC-V support
• Container Integration: Bootc and container-native workflows
• Cloud Integration: AWS, Azure, GCP image generation
• Edge Computing: IoT and edge deployment scenarios