Understanding Recipes

A BuildRecipe is the structured configuration that OpenFactory uses to create your custom Linux image. While you interact in natural language, OpenFactory translates your requirements into a validated recipe.

Recipe Structure

Every build recipe contains these key sections:

{
  "name": "secure-web-server",
  "baseImage": "debian-bookworm",
  "features": ["ssh", "docker", "firewall"],
  "services": [...],
  "users": [...],
  "security": {...},
  "tests": [...]
}

Core Fields

name

A unique identifier for your configuration:

"name": "production-web-server"

baseImage

The Linux distribution to build from:

features

Pre-built capability modules to include:

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

See Features for the complete list.

Service Configuration

Services are features with custom settings:

"services": [
  {
    "name": "ssh",
    "config": {
      "port": 2222,
      "allow_root": false,
      "disable_password_auth": true
    }
  }
]

Each service has its own configuration options. See Services for details.

User Management

Define system users:

"users": [
  {
    "username": "admin",
    "shell": "/bin/bash",
    "groups": ["sudo", "docker"],
    "vyattaLevel": "admin"
  },
  {
    "username": "deploy",
    "shell": "/bin/bash",
    "groups": ["docker"]
  }
]

The vyattaLevel field is specific to Elster OS for Vyatta configuration access.

Security Settings

Configure security hardening:

"security": {
  "hardeningLevel": "strict",
  "auditLogging": true,
  "automaticUpdates": true
}

Hardening levels:

• minimal - Basic security defaults
• standard - Recommended for most use cases
• strict - CIS benchmark compliance

Desktop Configuration

For desktop images (Ubuntu/Debian with desktop feature):

"desktop": {
  "theme": "dark",
  "wallpaper": "/path/to/wallpaper.png",
  "favorites": ["firefox.desktop", "terminal.desktop"]
}

Startup Scripts

Run custom commands at first boot:

"startupScripts": [
  {
    "name": "init-application",
    "script": "#!/bin/bash\necho 'System initialized' > /var/log/init.log"
  }
]

Tests

Define custom verification tests:

"tests": [
  {
    "description": "Verify web server",
    "assertions": [
      {
        "type": "service_running",
        "params": { "service": "nginx" }
      },
      {
        "type": "port_listening",
        "params": { "port": 80 }
      }
    ]
  }
]

See Custom Assertions for all assertion types.

Recipe Validation

OpenFactory validates every recipe before building:

• Schema validation - All fields match expected types
• Dependency checking - Required features are included
• Conflict detection - Incompatible options are flagged
• Security review - Dangerous configurations are warned

Viewing Your Recipe

To see the generated recipe for any build:

1. Open a conversation
2. Click Build Details
3. Select Recipe tab

You can also ask OpenFactory: “Show me the full recipe for this build”

Recipe Versioning

Each build creates a new version of the recipe. You can:

• Compare versions - See what changed between builds
• Revert - Go back to a previous configuration
• Fork - Create a new variant from an existing recipe

Best Practices

1. Start minimal - Add features incrementally
2. Use specific versions - Specify exact package versions for reproducibility
3. Test thoroughly - Add custom assertions for critical functionality
4. Document intent - Name recipes descriptively

Next Steps

• Base Images - Choose the right distribution
• Features - Available capability modules
• Services - Service configuration options