Configuration

Variables

Secrets, user configuration, system values, and port variables in Lawn templates.

Custom templates are not yet supported in the app. For now, we're temporarily curating the catalog. Support for importing and sharing custom templates is coming soon.

Lawn's variable system handles secrets, user configuration, and system values. Variables are defined in the template, generated or collected at install time, and injected into containers at startup.

Variable Types

Type	Declared in	Resolved	Use case
Generated Secret	`x-lawn.variables`	At install	Passwords, API keys, tokens
User Provided	`x-lawn.variables`	At install (user input)	Values the user must supply
System	Built-in	At startup	Timezone, UID, GID
Port	Built-in	At startup	Host port assignments

Variables declared in x-lawn.variables are part of the template's top-level configuration. For per-service environment annotations (descriptions, categories, UI hints), 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:
  variables:
    SECRET_KEY:
      source: generatedSecret   # <---
      length: 50
      displayName: "Secret Key"
      description: "Application secret key for session signing."

Field	Default	Description
`length`	32	Character count of the generated string
`displayName`	—	Human-readable label for the UI (required)
`description`	—	Explanation shown in the UI

Generated secrets are created once at install time and never change.

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:
  variables:
    ADMIN_PASSWORD:
      source: userProvided   # <---
      displayName: "Admin Password"
      description: "Password for the admin account."

The install button is 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.

System Variables

These are always available in every template. Never declare them in x-lawn.variables:

Variable	Description	Example
`TIMEZONE`	User's IANA timezone	`Europe/Amsterdam`
`UID`	Host user ID	`501`
`GID`	Host group ID	`20`

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:

Variable	Description
`HOST_PORT_<N>`	Resolved host port for container port N

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

Usage in Compose Files

Variables use substitution syntax in environment values:

services:
  db:
    image: <image-url>
    environment:
      POSTGRES_PASSWORD: ${POSTGRES_PASSWORD:-changeme}
      TZ: ${TIMEZONE:-UTC}

Lawn substitutes the real values at runtime.

Substitution Syntax

Lawn supports the full Docker Compose variable substitution syntax:

Syntax	Description
`$VAR` or `${VAR}`	Substitute the value of `VAR`
`${VAR:-default}`	Use `default` if `VAR` is unset or empty
`${VAR-default}`	Use `default` if `VAR` is unset
`${VAR:+replacement}`	Use `replacement` if `VAR` is set and non-empty
`${VAR+replacement}`	Use `replacement` if `VAR` is set
`${VAR:?error}`	Error if `VAR` is unset or empty
`${VAR?error}`	Error if `VAR` is unset
`$$`	Literal `$` (escaped)

The most common form is ${VAR:-default}, which provides a fallback when the variable hasn't been set.

When to Use What

Scenario	Approach
Passwords and secrets the user doesn't choose	`generatedSecret` in `x-lawn.variables`
Values the user must provide (API keys, repo URLs)	`userProvided` in `x-lawn.variables`
Static settings that benefit from a UI label	`x-lawn.environment` on the service
Timezone, user/group IDs	System variables (always available)
Dynamic port assignments	Port variables (always injected)