Variables

Lawn's configuration system handles three categories of values:

1. Secrets — Generated passwords and API keys
2. User input — Values provided during installation
3. Configuration — Selectable options with typed controls (toggles, pickers, number fields)

Variables are defined in the template, resolved at install time, and injected into containers at startup. Display strings (displayName, description, option labels) live in the localization file, not in the YAML.

Variable Types

For per-service environment metadata (format hints, descriptions), see Environment Metadata.

Generated Secrets

A random alphanumeric string created at install time. Use for passwords, API keys, and tokens that users don't need to choose.

x-lawn:
  config:
    SECRET_KEY:
      source: generatedSecret
      length: 50

Generated secrets are created once at install time and never change. Lawn stores the value per-instance so it survives container restarts and updates.

User Provided

A value the user supplies during installation. The CLI prompts interactively, and the GUI shows a required field in the install sheet.

x-lawn:
  config:
    ADMIN_PASSWORD:
      source: userProvided

The install button stays disabled until all userProvided variables have values. If the compose environment has a ${VAR:-default} fallback, that default is used when no value is provided.

For non-interactive installs, supply values with --var flags:

lawn catalog install github-actions-runner --var REPO_URL=https://github.com/your-org/your-repo

Config Options

Config variables can define selectable options, where each option carries a compose overlay that Lawn merges as an additional layer. This gives users a curated set of choices instead of raw environment variable editing.

x-lawn:
  config:
    DIFFICULTY:
      value: easy
      weight: 10
      options:
        peaceful:
          compose:
            services:
              minecraft:
                environment:
                  DIFFICULTY: peaceful
        easy:
          compose:
            services:
              minecraft:
                environment:
                  DIFFICULTY: easy
        normal:
          compose:
            services:
              minecraft:
                environment:
                  DIFFICULTY: normal
        hard:
          compose:
            services:
              minecraft:
                environment:
                  DIFFICULTY: hard

Each option's compose block is a standard compose document fragment. When the user selects "hard", Lawn merges that fragment into the active configuration — setting DIFFICULTY: hard in the container's environment.

Input Types

The inputType field controls how the UI renders the config variable:

Boolean toggle — use inputType: boolean with exactly two options:

PVP:
  inputType: boolean
  value: true
  weight: 30
  options:
    "true":
      compose:
        services:
          minecraft:
            environment:
              PVP: "TRUE"
    "false":
      compose:
        services:
          minecraft:
            environment:
              PVP: "FALSE"

The localization file provides labels for each option (e.g., "On"/"Off" or "Enabled"/"Disabled").

Number input — use inputType: number for integer values:

SPAWN_PROTECTION:
  inputType: number
  value: 16
  weight: 170

Text input — use inputType: text for free-form strings:

SEED:
  inputType: text
  value: ""
  weight: 130

Display Ordering

The weight field controls the display order in the UI. Lower values appear first. Variables with the same weight are sorted alphabetically. The default is 0.

x-lawn:
  config:
    DIFFICULTY:
      weight: 10    # Appears first
    HARDCORE:
      weight: 20    # Appears second
    PVP:
      weight: 30    # Appears third

Config Variable Fields

System Variables

These are always available in every template — Lawn injects them automatically.

Use them with fallbacks: ${TIMEZONE:-UTC}, ${UID:-1000}, ${GID:-1000}.

Port Variables

The engine injects HOST_PORT_<N> for each exposed port at container start:

For example, if container port 8080 maps to host port 51811, then HOST_PORT_8080=51811.

Usage in Compose Files

Use substitution syntax in environment values to reference variables:

services:
  db:
    image: postgres:15
    environment:
      POSTGRES_PASSWORD: ${POSTGRES_PASSWORD:-changeme}
      TZ: ${TIMEZONE:-UTC}

Lawn substitutes the real values at runtime. The :-default fallback keeps compose files valid for standalone use with docker compose up.

Substitution Syntax

Lawn supports the full Docker Compose variable substitution syntax:

When to Use What