Schéma receptury

Receptury OpenFactory používají JSON ve snake_case. Kanonický formát má malou obálku na nejvyšší úrovni, objekt os pro konfiguraci operačního systému a pole scenarios pro ověření po sestavení.

Validace ukazuje, že rozpoznaná pole mají přijatelný tvar. Nedokazuje, že každý balíček existuje, že každé požadované chování bylo zohledněno, ani že obraz a testy uspějí. Neznámá pole mohou být kvůli zpětné kompatibilitě ignorována; vždy zkontrolujte normalizovanou recepturu vrácenou produktem.

Kanonická obálka


{
  "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"]
}

Nepoužívejte pole camelCase jako baseImage nebo startupScripts. Validátor kompatibility přijme některé starší ploché receptury, ale normalizovaný výstup vnořuje pole OS pod os. Nové integrace by měly posílat kanonický formát.

Pole nejvyšší úrovně

Pole	Typ	Povinné/výchozí	Význam
`name`	string	Povinné; 3–100 znaků	Stabilní interní název receptury
`display_name`	string nebo null	Volitelné; 1–100 znaků	Název pro lidi
`description`	string	`""`	Zamýšlený výsledek a hranice
`base_image`	string	`debian-trixie`	Distribuce/cíl sestavení; použijte aktuální seznam v konzoli
`task`	string nebo null	Volitelné	Operační cíl
`executor`	string nebo null	Volitelné	Technologie, která má úkol provést
`use_case`	string	`General`	Hlavní případ použití
`hardware`	object	Výchozí hodnoty níže	Požadavky na nasazení
`os`	object	Prázdný/výchozí objekt	Balíčky OS, uživatelé, služby, zabezpečení, desktop, installer a skripty
`scenarios`	array	`[]`	Testovací topologie a cíle
`publish_to`	string array	`["local"]`	Požadovaná cílová umístění výstupu
`delivery`	object	`{}`	Další deklarovaná konfigurace doručení
`community`	boolean	`false`	Požádat o viditelnost na community marketplace; pravidla publikace platí dál

Pokročilá pole závislá na cíli existují pro remasterování zdrojového ISO, payloady hosta Proxmox, provenienci politik a integrace doručení. Použijte editor nebo kontrakt API nasazené verze místo kopírování starého příkladu.

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 je pc, phone nebo raspberry_pi; podporované hodnoty zařízení závisí na cíli. architecture je x86_64 nebo aarch64. Hodnoty GPU pojmenovávají podporovaného dodavatele nebo kombinaci. Jde o deklarované požadavky, ne o důkaz, že výsledný obraz byl testován na odpovídajícím fyzickém hardwaru.

Objekt OS

Běžná pole os:

Pole	Typ	Účel
`features`	string array	Registrované moduly funkcí
`packages`	string array	Nativní balíčky k požádání
`excluded_packages`	string array	Balíčky, které po rozšíření funkcí nesmí být přítomny
`custom_packages`	array	Zdrojová repozitáře k zabalení podporovanou cestou sestavení
`package_overrides`	array	Explicitní operace add, remove nebo replace
`extra_repos`	string array	Další repozitáře; důvěra a práce s klíči stále vyžadují kontrolu
`services`	array	Pojmenované zapnutí a konfigurace služeb
`users`	array	Účty a skupiny lokální v obrazu
`security`	object	Deklarované volby hardeningu, šifrování, auditu, SELinux a fail2ban
`networking`	object	Záměr rozhraní a sítě
`desktop_settings`	object	Vzhled a chování desktopu
`branding`	object	Identita distribuce a assety
`runtime`	object	Identita init/služby/správce balíčků
`boot`	object	Argumenty jádra a volby GRUB
`installer`	object	Konfigurace install-to-disk
`persistence`	object	Trvalost live a politika zón
`integrity`	object	Požadovaná nastavení dm-verity, Secure Boot a IMA/EVM
`file_attachments`	array	Dříve nahrané soubory identifikované přes `file_id`
`startup_scripts`	array	Omezené jednorázové skripty systemd
`time_zone`	string nebo null	Nastavení časového pásma obrazu

Přítomnost pole integrity nebo security vyjadřuje záměr konfigurace. Není důkazem, že mechanismus byl vytvořen, vynucen za běhu nebo kvalifikován pro režim compliance. Vyžadujte odpovídající důkazy ze sestavení a testů.

Uživatelé


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

Jména uživatelů a skupin jsou omezena na bezpečné znaky a délku linuxových účtů. Bez nastaveného password vznikne účet uzamčený heslem pro workflow pouze s klíčem nebo s přihlašovacími údaji až při nasazení. Vyhněte se nešifrovaným přihlašovacím údajům v uložených recepturách.

Služby


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

config závisí na službě. Syntakticky platný klíč může generátor, který ho neimplementuje, ignorovat. Ověřte normalizovanou recepturu, vygenerovanou konfiguraci a chování hosta.

Zabezpečení a 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"
    }
  }
}

Typy installeru závisí na cíli (calamares, anaconda nebo elster-mobile). Po zapnutí installeru následuje test instalace na jednorázový disk; ikona na live desktopu nedokazuje, že instalace funguje.

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"
      }
    ]
  }
}

Přijme se nejvýše 32 startup skriptů. Příkazy musí být neprázdné a nesmí obsahovat bajty NUL. Považujte je za shell kód s právy root, pokud run_as neříká jinak; kontrolujte idempotenci, quoting, selhání sítě a únik tajemství.

Scénáře a 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}
            }
          ]
        }
      ]
    }
  ]
}

Scénář může také definovat topology s VM a sítěmi, testy ve formátu benchmark a nastavení CIS. Chybějící topologie defaultuje na běžnou cestu s jednou VM. Assertions potřebují lidsky čitelný description a parametry podle typu. Neznámé typy assertions mohou projít parsováním schématu; ověřte podporu v runneru, než je berete jako důkaz.

Úplný minimální příklad


{
  "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"]
}

Workflow validace

Validujte JSON v aktuálním editoru receptur, API nebo MCP nástroji validate_recipe.
Porovnejte vrácenou normalizovanou recepturu s původním požadavkem.
Zahozená neznámá pole považujte za chybu receptury, ne za úspěšnou konfiguraci.
Sestavujte až poté, co jsou explicitní požadavky zohledněny.
Prohlédněte vygenerované důkazy a spusťte assertions proti výslednému hostu.

Viz Váš první build pro postup při selhání a obnově stažení.