Схема рецепта

Рецепти OpenFactory використовують JSON у snake_case. Канонічний формат має невеликий top-level envelope, об’єкт os для конфігурації операційної системи та масив scenarios для перевірки після збірки.

Валідація доводить, що визнані поля мають прийнятну форму. Вона не доводить, що кожен package існує, кожна запитана поведінка представлена, або що image і tests успішні. Невідомі поля можуть ігноруватися для backward compatibility, тому завжди переглядайте нормалізований рецепт, який повертає продукт.

Canonical Envelope


{
  "name": "debian-web-check",
  "display_name": "Debian Web Check",
  "description": "Small Debian image with explicit smoke tests.",
  "base_image": "debian-trixie",
  "use_case": "Server evaluation",
  "hardware": {},
  "os": {},
  "scenarios": [],
  "publish_to": ["local"]
}

Do not use camelCase fields such as baseImage or startupScripts. Compatibility validator accepts some older flat recipes, but normalized output nests OS fields under os. New integrations should send canonical format.

Top-Level Fields

Field	Type	Required/default	Значення
`name`	string	Required; 3–100 characters	Stable internal recipe name
`display_name`	string or null	Optional; 1–100 characters	Human-facing name
`description`	string	`""`	Intended outcome and boundary
`base_image`	string	`debian-trixie`	Distribution/build target; use the current console list
`task`	string or null	Optional	Operational goal
`executor`	string or null	Optional	Technology expected to perform the task
`use_case`	string	`General`	Primary use case
`hardware`	object	Defaults shown below	Deployment requirements
`os`	object	Empty/default object	OS packages, users, services, security, desktop, installer, and scripts
`scenarios`	array	`[]`	Test topologies and objectives
`publish_to`	string array	`["local"]`	Requested output destinations
`delivery`	object	`{}`	Additional declared delivery configuration
`community`	boolean	`false`	Request community-marketplace visibility; publication policy still applies

Advanced target-specific fields exist for source-ISO remastering, Proxmox guest payloads, policy provenance, delivery integrations. Use editor or API contract for deployed release instead of copying old example.

Hardware


{
  "hardware": {
    "platform": "pc",
    "architecture": "x86_64",
    "gpu": null,
    "min_cpu_cores": 2,
    "min_memory_gb": 4,
    "min_storage_gb": 16,
    "nic_count": 1
  }
}

platform is pc, phone, or raspberry_pi; supported device values target-specific. architecture is x86_64 or aarch64. GPU values name supported vendor or vendor combination. These declared requirements, not proof resulting image tested on matching physical hardware.

OS Object

Common os fields:

Field	Type	Purpose
`features`	string array	Registered feature modules
`packages`	string array	Native packages to request
`excluded_packages`	string array	Packages that must remain absent after feature expansion
`custom_packages`	array	Source repositories to package through the supported build path
`package_overrides`	array	Explicit add, remove, or replace operations
`extra_repos`	string array	Additional repositories; trust and key handling still require review
`services`	array	Named service enablement and configuration
`users`	array	Image-local accounts and groups
`security`	object	Declared hardening, encryption, audit, SELinux, and fail2ban choices
`networking`	object	Interface and network intent
`desktop_settings`	object	Desktop appearance and behavior
`branding`	object	Distribution identity and assets
`runtime`	object	Init/service/package-manager identity
`boot`	object	Kernel arguments and GRUB choices
`installer`	object	Install-to-disk configuration
`persistence`	object	Live persistence and zone policy
`integrity`	object	Requested dm-verity, Secure Boot, and IMA/EVM settings
`file_attachments`	array	Previously uploaded files identified by `file_id`
`startup_scripts`	array	Bounded systemd one-shot scripts
`time_zone`	string or null	Image time-zone setting

Presence of integrity or security field is configuration intent. Not evidence mechanism produced, enforced at runtime, or qualified for compliance regime. Require matching build and test evidence.

Users


{
  "os": {
    "users": [
      {
        "username": "deploy",
        "full_name": "Deployment Operator",
        "groups": ["sudo"],
        "shell": "/bin/bash"
      }
    ]
  }
}

User and group names limited to safe Linux account characters and length. Leaving password unset creates password-locked account for key-only or deployment-time credential workflows. Avoid plaintext credentials in saved recipes.

Services


{
  "os": {
    "services": [
      {
        "name": "ssh",
        "enabled": true,
        "config": {
          "port": 22,
          "disable_password_auth": true
        }
      }
    ]
  }
}

config service-specific. Syntactically valid key can still be ignored by generator that does not implement it. Verify normalized recipe, generated configuration, guest behavior.

Security and Installer


{
  "os": {
    "security": {
      "hardening_level": "standard",
      "disk_encryption": false,
      "audit_logging": true,
      "selinux": false,
      "fail2ban": true
    },
    "installer": {
      "enabled": false,
      "type": "calamares",
      "desktop_launcher": true,
      "bootloader": "grub",
      "delivery": [],
      "user_setup": "build_time"
    }
  }
}

Installer types target-dependent (calamares, anaconda, or elster-mobile). Enabling installer must be followed by disposable-disk install test; icon in live desktop not proof installation works.

Startup Scripts


{
  "os": {
    "startup_scripts": [
      {
        "name": "write-build-marker",
        "description": "Create a local marker after networking is available.",
        "command": "install -m 0644 /dev/null /var/lib/example-ready",
        "packages": [],
        "run_as": "root",
        "after": "network.target"
      }
    ]
  }
}

At most 32 startup scripts accepted. Commands must be nonempty and cannot contain NUL bytes. Treat as root-capable shell code unless run_as says otherwise; review idempotency, quoting, network failure, secret exposure.

Scenarios and Assertions


{
  "scenarios": [
    {
      "id": "primary-smoke",
      "name": "Primary image smoke test",
      "enabled": true,
      "tests": ["boot", "login", "packages"],
      "custom_tests": [
        {
          "description": "Confirm SSH is enabled on the configured port.",
          "assertions": [
            {
              "type": "service_enabled",
              "description": "The SSH service starts at boot.",
              "params": {"service": "ssh"}
            },
            {
              "type": "port_listening",
              "description": "The guest listens on TCP port 22.",
              "params": {"port": 22}
            }
          ]
        }
      ]
    }
  ]
}

Scenario can also define topology with VMs and networks, benchmark-format tests, CIS settings. Omitted topology defaults to normal single-VM path. Assertions need human-readable description and type-specific params. Unknown assertion types may survive schema parsing, confirm runner supports them before treating as evidence.

Complete Minimal Example


{
  "name": "debian-web-check",
  "display_name": "Debian Web Check",
  "description": "Debian image with SSH, curl, and explicit smoke tests.",
  "base_image": "debian-trixie",
  "use_case": "Server evaluation",
  "hardware": {
    "platform": "pc",
    "architecture": "x86_64",
    "min_cpu_cores": 2,
    "min_memory_gb": 4,
    "min_storage_gb": 16,
    "nic_count": 1
  },
  "os": {
    "features": ["ssh"],
    "packages": ["curl"],
    "users": [
      {
        "username": "deploy",
        "groups": ["sudo"],
        "shell": "/bin/bash"
      }
    ],
    "services": [
      {
        "name": "ssh",
        "enabled": true,
        "config": {"port": 22, "disable_password_auth": true}
      }
    ],
    "security": {
      "hardening_level": "standard",
      "audit_logging": true
    },
    "installer": {"enabled": false}
  },
  "scenarios": [
    {
      "id": "primary-smoke",
      "name": "Primary image smoke test",
      "enabled": true,
      "tests": ["boot", "login", "packages"]
    }
  ],
  "publish_to": ["local"]
}

Validation Workflow

Validate JSON through current recipe editor, API, or MCP validate_recipe tool.
Compare returned normalized recipe with original request.
Treat dropped unknown fields as defect in recipe, not successful configuration.
Build only after explicit requirements represented.
Inspect generated evidence and run assertions against resulting guest.

See Your First Build for failure and download recovery guidance.