One YAML definition can power ordering and trusted Server Content.

Workflow

Author outside runtime, validate, then publish.

1. Copy the canonical template to a working filename outside catalog/products/.
2. Replace product IDs, display text, platform, locations, resources, pricing, ports, and non-secret variables.
3. Add trusted artifacts with real lowercase SHA-256 digests and OS-native target paths.
4. Write idempotent install and remove actions for each supported platform.
5. Run the validator against the single file.
6. Move the validated file to catalog/products/, then validate the full runtime catalog.

Active application, game, or custom-none products can appear in Order flows. Server Content additionally requires a valid content_lifecycle.

Document shape

Every document uses schema_version: catalog.product.v1 and the required product, resource_requirements, and pricing sections.

schema_version: catalog.product.v1
product: {}
resource_requirements: {}
pricing: {}

Implemented optional sections are ports, variables, environment, network, volumes, health, monitoring, configuration, recipes, content_lifecycle, agent_deployment, startup_profiles, service_connection_variables, and managed_service.

Resources and pricing

Customer-facing resource defaults are Standard Memory, Burst Memory, and Storage. CPU is intentionally not a customer-facing limit; CPU fields such as cpu_cores, recommended_cpu_cores, and cpu_limit are rejected.

Pricing uses integer minor units with uppercase currency codes. Each component needs a stable key, label, unit, interval, amount_minor, and taxable.

Ports and options

variables are non-secret customer options. Supported types are text, integer, boolean, and port. Port variables such as APP_PORT provide a base port; current Server Content reserves a 10-port block from that base.

ports declares listeners with a key, label, protocol, container port, purpose, and public flag. Use duplicate port numbers when the same listener uses both TCP and UDP. Keep protocol choices in trusted YAML metadata when the customer should not select them.

Trusted content lifecycle

content_lifecycle is provider-controlled execution metadata. Browsers submit only product IDs and validated options; artifact references, scripts, interpreters, and timeouts are resolved server-side from YAML before the agent receives a content job.

content_lifecycle:
  supported_platforms: [windows, linux]
  platforms:
    windows:
      installed_state: {}
      artifacts: []
      actions: {}
    linux:
      installed_state: {}
      artifacts: []
      actions: {}

Each lifecycle variant can define installed_state.marker_path, installed_state.version, trusted artifacts, and required actions.install and actions.remove. Actions use interpreter set to powershell or sh, positive timeout_seconds, optional string arguments, and a multiline script.

Scripts must be idempotent, quote paths carefully, stop only known processes for the content path, and remove only owned install directories. Do not put passwords, tokens, private keys, provider keys, or customer secrets in YAML.

Canonical template

This public template is generic and intentionally uses placeholder artifact hashes. Replace every example value before publishing a runtime product.

schema_version: catalog.product.v1
product:
  id: prod-example-content
  key: example-content
  type: application
  name: Example Content
  summary: Replace every example value before publishing.
  status: draft
  version: "1.0.0"
  platform: any
  locations: [loc-dal-1]
resource_requirements:
  memory_mb: 512
  recommended_memory_mb: 1024
  burst_memory_mb: 2048
  storage_mb: 1024
  recommended_storage_mb: 4096
pricing:
  currency: USD
  components:
    - key: base
      label: Example Content
      unit: application
      interval: monthly
      amount_minor: 0
      taxable: false
variables:
  - key: APP_PORT
    label: Base port
    type: port
    required: true
    default: 7777
environment:
  APP_PORT: "7777"
  APP_PROTOCOL: both
network:
  mode: nat
  primary_port_key: app-tcp
  port_block_size: 10
ports:
  - key: app-tcp
    label: TCP listener
    protocol: tcp
    container_port: 7777
    purpose: primary-listener
    public: true
  - key: app-udp
    label: UDP listener
    protocol: udp
    container_port: 7777
    purpose: primary-listener
    public: true
content_lifecycle:
  supported_platforms: [windows, linux]
  platforms:
    windows:
      installed_state:
        marker_path: C:/container-engine/content/example-content/install-state.json
        version: "1.0.0"
      artifacts:
        - key: example-windows-amd64
          source_ref: project://catalog-artifacts/example-content/example-windows-amd64.exe
          target_path: C:/container-engine/content/example-content/example-windows-amd64.exe
          sha256: 0000000000000000000000000000000000000000000000000000000000000000
      actions:
        install:
          interpreter: powershell
          timeout_seconds: 120
          script: |
            $ErrorActionPreference = 'Stop'
            $installDir = 'C:\container-engine\content\example-content'
            New-Item -ItemType Directory -Force -Path $installDir | Out-Null
            Write-Output 'Example Content installed from trusted YAML.'
        remove:
          interpreter: powershell
          timeout_seconds: 60
          script: |
            $installDir = 'C:\container-engine\content\example-content'
            if (Test-Path -LiteralPath $installDir) { Remove-Item -LiteralPath $installDir -Recurse -Force }
            Write-Output 'Example Content removed.'
    linux:
      installed_state:
        marker_path: /opt/container-engine/content/example-content/install-state.json
        version: "1.0.0"
      artifacts:
        - key: example-linux-amd64
          source_ref: project://catalog-artifacts/example-content/example-linux-amd64
          target_path: /opt/container-engine/content/example-content/example-linux-amd64
          sha256: 0000000000000000000000000000000000000000000000000000000000000000
      actions:
        install:
          interpreter: sh
          timeout_seconds: 120
          script: |
            set -eu
            install_dir="/opt/container-engine/content/example-content"
            mkdir -p "$install_dir"
            echo "Example Content installed from trusted YAML."
        remove:
          interpreter: sh
          timeout_seconds: 60
          script: |
            set -eu
            install_dir="/opt/container-engine/content/example-content"
            rm -rf "$install_dir"
            echo "Example Content removed."
agent_deployment:
  image: example-content-runtime:1.0.0
  pull_policy: never
  restart_policy: unless-stopped

Validation

Validate a single authoring file before moving it into the runtime catalog:

php bin/ce-catalog-validate catalog/templates/content-application.template.yaml
php bin/ce-catalog-validate catalog/examples/server-port-test-dual-os.yaml

Validate runtime products after placing a file in catalog/products/:

php bin/ce-catalog-validate

The validator rejects unknown top-level keys, unsupported schema versions, invalid enum values, non-integer prices or resources, burst memory below Standard Memory, CPU customer limits, malformed ports, malformed lifecycle actions, non-lowercase SHA-256 digests, and secret-like keys or values.