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

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

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

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

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

### Package Categories

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

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

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

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

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

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