Lawn Compose

Extensions

Health checks, environment metadata, notices, init files, and directories using x-lawn.

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.

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

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

Health Checks

Lawn-specific health checks that determine when a service is ready. These complement the standard healthcheck field from the Compose Specification.

services:
  app:
    x-lawn:
      healthChecks:
        - type: http
          description: "Web UI is accessible"
          path: /health
          expectedStatus: 200
          followRedirects: true

HTTP health checks:

Field	Default	Description
`type`	—	Must be `http`
`description`	—	Human-readable check description
`path`	—	URI path to check
`expectedStatus`	`200`	Expected HTTP status code
`followRedirects`	`true`	Follow 3xx redirects

Command health checks:

x-lawn:
  healthChecks:
    - type: command
      description: "Database is accepting connections"
      command: ["/bin/sh", "-c", "pg_isready -U postgres"]

Timing fields (shared by both types):

Field	Default	Description
`intervalSeconds`	`30`	Seconds between checks
`timeoutSeconds`	`10`	Seconds before a check times out
`retries`	`3`	Failures before marking unhealthy
`startPeriodSeconds`	`60`	Grace period before checks begin

Environment Metadata

Add UI descriptions and categories to environment variables. This is for display annotations only — it doesn't change how the variables work.

services:
  db:
    environment:
      POSTGRES_USER: postgres
      POSTGRES_DB: app
    x-lawn:
      environment:
        POSTGRES_USER:
          description: "PostgreSQL username."
          category: advanced
        POSTGRES_DB:
          description: "Default database name."
          category: advanced

Field	Description
`description`	Human-readable explanation shown in the UI
`category`	Grouping: `required`, `optional`, `advanced`, or `internal` (hidden from UI)
`format`	Validation hint: `string`, `integer`, `boolean`, `port`, or `url`
`group`	Display group name for organizing variables into sections

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:

services:
  app:
    x-lawn:
      notices:
        - id: default-credentials
          title: Default Credentials
          style: info
          elements:
            - type: field
              label: Username
              value: admin
            - type: field
              label: Password
              value: changeme
            - type: text
              content: "Change these in **Settings > Security** after your first login."

Notice Fields

Field	Description
`id`	Unique identifier (used to track dismissal state)
`title`	Short heading displayed in the banner
`style`	`info` (blue) for general guidance, `warning` (orange) for critical actions
`elements`	List of content blocks

Element Types

Text — Markdown content:

- type: text
  content: "Visit **Settings > General** to complete setup."

Field — Label-value pair with a copy button:

- type: field
  label: Username
  value: admin

Field with variable source — Resolves the current value of an environment variable:

- type: field
  label: Password
  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.

Notice Guidelines

Keep notices to 2-3 per template maximum
Only use notices for information users genuinely need to act on
Use info style for setup guidance and warning for critical actions
Notices are collected from all services in the compose file
Users can dismiss notices and restore them from the instance menu

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"

Field	Description
`source`	Filename in the template's `init-files/` directory
`containerPath`	Absolute path inside the container

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.

Files are overwritten on every start, so the template always provides the latest version.

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.