Extensions

The Compose Specification allows custom x- prefixed keys as extensions. Lawn uses x-lawn at two levels:

• Top-level — template-wide settings like config declarations and compatibility
• Per-service — health checks, environment metadata, notices, directories, and init files

User-facing strings (descriptions, titles, labels, content) live in the localization file, not in the YAML template.

Compatibility

Declare the minimum Lawn version required to use this template. Lawn filters out templates whose minLawnVersion exceeds the running app version.

x-lawn:
  compatibility:
    minLawnVersion: 0.2.0

Health Checks

Lawn-specific health checks that determine when a service is ready. These complement the standard healthcheck field from the Compose Specification. Each health check has an id used as a localization key.

services:
  app:
    x-lawn:
      healthChecks:
        - id: web-ui
          type: http
          path: /health
          expectedStatus: 200
          followRedirects: true

The description for each health check lives in locales/en.json under services.<svc>.healthChecks.<id>.description.

HTTP health checks:

Command health checks:

services:
  db:
    x-lawn:
      healthChecks:
        - id: db-ready
          type: command
          command: ["/bin/sh", "-c", "pg_isready -U postgres"]

Timing fields (shared by both types):

Environment Metadata

Metadata for environment variables declared in the service's environment: section. Provides format hints for validation.

services:
  db:
    environment:
      POSTGRES_USER: postgres
      POSTGRES_DB: app
    x-lawn:
      environment:
        POSTGRES_USER:
          format: string
        POSTGRES_DB:
          format: string

Environment entries can also be bare keys with no value — the key's presence registers the variable with Lawn, and descriptions come from the localization file:

x-lawn:
  environment:
    EULA:
    TZ:
    VERSION:

Descriptions and group labels live in locales/en.json under services.<svc>.environment.<VAR>. See Localization for the full JSON structure.

Notices

Notices are dismissible banners shown on the instance detail panel after installation. Use them to surface important information: default credentials, required setup steps, or warnings about things users should not change.

Defining Notices

Notices are defined in a service's x-lawn.notices array. The YAML contains only structural fields — titles, labels, and content live in the localization file.

services:
  app:
    x-lawn:
      notices:
        - id: default-credentials
          style: info
          elements:
            - id: username
              type: field
              value: admin
            - id: password
              type: field
              source: ADMIN_PASSWORD
              container: app
            - id: setup-note
              type: text

The corresponding localization entry provides the user-facing strings:

{
  "services": {
    "app": {
      "notices": {
        "default-credentials": {
          "title": "Default Credentials",
          "elements": {
            "username": { "label": "Username" },
            "password": { "label": "Password" },
            "setup-note": { "content": "Change these in **Settings > Security** after your first login." }
          }
        }
      }
    }
  }
}

Notice Fields

Element Types

Text — Markdown content (provided via localization JSON):

- id: setup-note
  type: text

Field — Static label-value pair with a copy button:

- id: username
  type: field
  value: admin

Source field — Resolves the current value of an environment variable. Uses the same type: field as static fields, but includes source and container to look up the live value:

- id: password
  type: field
  source: ADMIN_PASSWORD
  container: app

The source field reads the resolved value of the named variable from the specified container, keeping credential notices accurate even after overrides. Labels for both static and source field elements come from the localization file.

Notice Guidelines

• Use info style for setup guidance and warning for critical actions
• Notices are collected from all services in the compose file

Init Files

Init files are copied from the template into the container's volume mounts before each start. They're useful for configuration overrides that need to exist on disk when the container boots.

Init files are defined in a service's x-lawn.initFiles array:

services:
  app:
    x-lawn:
      initFiles:
        - source: "override.config.php"
          containerPath: "/var/www/html/config/override.config.php"

The containerPath must fall within a declared volume mount. Lawn resolves it to a host path using the volume mapping. For example, if the volume is ./www:/var/www and the containerPath is /var/www/html/config/foo.php, the file is written to {volume_host_path}/html/config/foo.php.

Create Directories

The x-lawn.createDirectories array lists host-side directories to create before the container starts. Paths follow the same conventions as volume host paths — relative paths resolve against the instance's data/ directory.

services:
  app:
    x-lawn:
      createDirectories:
        - "./data/uploads"
        - "./data/cache"

This is useful when a volume mount covers a parent directory but the container expects specific subdirectories to exist on first startup.