Skip to Content
ReferenceRecipe Schema

Recipe Schema

Complete reference for the BuildRecipe JSON schema.

Schema Overview

{
  "name": "string",
  "baseImage": "string",
  "features": ["string"],
  "services": [ServiceConfig],
  "users": [UserConfig],
  "security": SecurityConfig,
  "desktop": DesktopConfig,
  "startupScripts": [ScriptConfig],
  "tests": [TestConfig]
}

Root Properties

name

Type: string Required: Yes

Unique identifier for the build configuration.

"name": "production-web-server"

baseImage

Type: string Required: Yes

Base Linux distribution to build from.

Valid values:

  • elster-os - Elster OS 13
  • elster-os-12 - Elster OS 12
  • debian-bookworm - Debian 12
  • debian-trixie - Debian 13
  • ubuntu-noble - Ubuntu 24.04 LTS
  • fedora-40 - Fedora 40
"baseImage": "debian-bookworm"

features

Type: string[] Required: No

List of feature modules to include.

"features": ["ssh", "docker", "firewall", "security-hardening"]

See Features for all options.

services

Type: ServiceConfig[] Required: No

Service configurations with custom settings.

"services": [
  {
    "name": "ssh",
    "config": {
      "port": 2222
    }
  }
]

users

Type: UserConfig[] Required: No

System users to create.

"users": [
  {
    "username": "admin",
    "groups": ["sudo"]
  }
]

security

Type: SecurityConfig Required: No

Security hardening configuration.

"security": {
  "hardeningLevel": "strict"
}

desktop

Type: DesktopConfig Required: No

Desktop customization (requires desktop feature).

"desktop": {
  "theme": "dark"
}

startupScripts

Type: ScriptConfig[] Required: No

First-boot scripts.

"startupScripts": [
  {
    "name": "init",
    "script": "#!/bin/bash\necho 'done'"
  }
]

tests

Type: TestConfig[] Required: No

Custom test definitions.

"tests": [
  {
    "description": "Verify app",
    "assertions": [...]
  }
]

ServiceConfig

interface ServiceConfig {
  name: string;
  config: Record<string, any>;
}

SSH Service Config

interface SSHConfig {
  port?: number;              // Default: 22
  allow_root?: boolean;       // Default: false
  disable_password_auth?: boolean; // Default: false
  timeout?: number;           // Default: 120
  client_alive_interval?: number; // Default: 60
  max_auth_tries?: number;    // Default: 6
}

UserConfig

interface UserConfig {
  username: string;           // Required
  shell?: string;             // Default: /bin/bash
  groups?: string[];          // Additional groups
  home?: string;              // Home directory
  comment?: string;           // User description
  vyattaLevel?: 'admin' | 'operator' | 'user'; // Elster OS only
}

SecurityConfig

interface SecurityConfig {
  hardeningLevel?: 'minimal' | 'standard' | 'strict';
  auditLogging?: boolean;
  automaticUpdates?: boolean;
}

DesktopConfig

interface DesktopConfig {
  theme?: 'light' | 'dark' | 'system';
  accentColor?: string;
  wallpaper?: string;
  favorites?: string[];
  fonts?: FontConfig;
  power?: PowerConfig;
  extensions?: string[];
}
 
interface FontConfig {
  interface?: string;
  document?: string;
  monospace?: string;
}
 
interface PowerConfig {
  screenBlankTimeout?: number;
  suspendOnIdle?: boolean;
  lidCloseAction?: string;
}

ScriptConfig

interface ScriptConfig {
  name: string;               // Required
  script: string;             // Required (with shebang)
  runAs?: string;             // Default: root
  timeout?: number;           // Max seconds
}

TestConfig

interface TestConfig {
  description: string;
  assertions: Assertion[];
}
 
interface Assertion {
  type: string;
  params: Record<string, any>;
}

See Assertion Types for all types.

Complete Example

{
  "name": "secure-production-server",
  "baseImage": "debian-bookworm",
  "features": [
    "ssh",
    "docker",
    "firewall",
    "security-hardening"
  ],
  "services": [
    {
      "name": "ssh",
      "config": {
        "port": 2222,
        "allow_root": false,
        "disable_password_auth": true,
        "timeout": 300,
        "client_alive_interval": 30,
        "max_auth_tries": 3
      }
    }
  ],
  "users": [
    {
      "username": "admin",
      "shell": "/bin/bash",
      "groups": ["sudo", "docker"],
      "comment": "System administrator"
    },
    {
      "username": "deploy",
      "shell": "/bin/bash",
      "groups": ["docker"],
      "comment": "Deployment account"
    }
  ],
  "security": {
    "hardeningLevel": "strict",
    "auditLogging": true,
    "automaticUpdates": true
  },
  "startupScripts": [
    {
      "name": "register-server",
      "script": "#!/bin/bash\ncurl -X POST https://mgmt.example.com/register -d \"hostname=$(hostname)\""
    }
  ],
  "tests": [
    {
      "description": "Verify security configuration",
      "assertions": [
        {
          "type": "service_running",
          "params": { "service": "ssh" }
        },
        {
          "type": "port_listening",
          "params": { "port": 2222 }
        },
        {
          "type": "user_exists",
          "params": {
            "username": "admin",
            "groups": ["sudo", "docker"]
          }
        },
        {
          "type": "file_contains",
          "params": {
            "path": "/etc/ssh/sshd_config",
            "content": "PermitRootLogin no"
          }
        }
      ]
    }
  ]
}

Validation

OpenFactory validates recipes before building:

  1. Schema validation - All fields match expected types
  2. Reference validation - Features and services exist
  3. Dependency checking - Required features included
  4. Conflict detection - Incompatible options flagged
  5. Security review - Dangerous configs warned
MCP IntegrationServiceNow Integration