Directory Structure
Every template is a directory. The directory name is the app's unique identifier (e.g., paperless-ngx, jellyfin).
my-app/
├── manifest.yaml
├── icon.svg
├── locales/
│ └── en.json
├── lawn-compose/
│ └── compose.yaml
└── init-files/
└── nginx.conf
| File | Purpose |
|---|---|
manifest.yaml | App metadata (name, category, icon, web port) |
icon.svg | App icon shown in the catalog |
locales/en.json | User-facing strings (display names, descriptions, labels) |
lawn-compose/compose.yaml | Current container configuration |
init-files/ | Files copied into the container before start (optional) |
manifest.yaml — App metadata
The manifest controls how the app appears in the catalog — its name, description, category, and web UI link.
id: my-app
name: My App
version: "1.2.0"
tagline: A short one-liner about what this app does.
description: |
A longer **markdown** description shown on the app detail page.
icon: server.rack # SF Symbol fallback (used when no icon file exists)
category: Utilities
webPort: 8080
All fields:
| Field | Type | Required | Description |
|---|---|---|---|
id | string | Yes | Unique identifier (must match the directory name) |
name | string | Yes | Display name |
version | string | No | App version shown in Lawn. Keep the value quoted. |
updateThrough | string | No | See Required intermediate versions. |
tagline | string | No | Short one-line description |
description | string | Yes | Full markdown description |
icon | string | Yes | SF Symbol name used as fallback when no icon file exists |
category | string | Yes | One of: Documents, Media, Development, Networking, Utilities, Databases, Monitoring |
tags | string | No | Search tags |
features | string | No | Feature bullet points |
screenshots | string | No | Screenshot identifiers |
links | Link | No | External links (github, docs, website) |
webPort | int | No | The container port for the web UI |
webScheme | string | No | URL scheme: http (default) or https |
webPath | string | No | Path appended to the web URL (e.g., /admin/) |
compatibility.minLawnVersion | string | No | Minimum Lawn version required to use this template (e.g., 0.2.0) |
Required intermediate versions
If an app must pass through earlier versions during an update, list those versions in updateThrough, oldest first:
updateThrough:
- "1.0.0"
- "2.0.0"
If several templates share a version, Lawn uses the newest. Use a Git commit ID instead to select a specific template.
icon.svg — App icon
The app icon shown in the catalog and instance detail views. The file must be named icon with one of the supported extensions:
| Format | Extension | Notes |
|---|---|---|
| SVG | .svg | Preferred. Scales to any size |
| PNG | .png | Use at least 256×256 pixels |
| HEIF | .heif | macOS native format |
.pdf | Vector format |
icon field.lawn-compose/ — Container configuration
Define your containers in lawn-compose/compose.yaml.
Publish changes by committing the app directory. Keep the repository history so older versions remain available.
Existing numbered compose filenames still work. To switch, rename the current file to compose.yaml and add its version to manifest.yaml.
See Format for compose file structure and Extensions for x-lawn features.
init-files/ — Startup files (optional)
Files in this directory are copied into the container's volume mounts before each start. This is useful for configuration files that need to exist on disk when the app boots — for example, a custom nginx config or a default settings file.
Each file is referenced by name in the compose file's x-lawn.initFiles array, which maps it to a path inside the container. Files are overwritten on every start, so the template always provides the latest version.
locales/ — User-facing strings
All display names, descriptions, option labels, notice titles, and element content live in a JSON localization file rather than in the YAML template. The YAML defines structure and behavior; the JSON provides presentation.
Every template must include a locales/en.json file. See Localization for the full JSON structure and field reference.