Development documentation may include features that are not in the latest release. Read the Lawn 0.8.1 guide.
Directory Structure
Template layout
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 | Optional local app icon shown in the catalog |
locales/en.json | Localized Compose configuration and extension strings |
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.
symbolFallback: server.rack # SF Symbol fallback when no icon image is available
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 |
symbolFallback | string | Yes | SF Symbol name used when no icon image is available |
iconURL | string | No | Hosted icon URL, preferred over a local icon file |
iconIsTemplate | bool | No | Render the icon as a monochrome template image using the foreground color. Defaults to false |
category | string | No | 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
A local icon file is optional when you use iconURL or the required symbolFallback. When iconURL is set, Lawn prefers the hosted artwork over the local file.
To bundle an icon shown in the catalog and instance detail views, name the file 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 |
symbolFallback.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
Compose configuration display names and descriptions, option labels, notice titles, and element content live in a JSON localization file. App names, taglines, and descriptions remain metadata in manifest.yaml.
Every template must include a locales/en.json file. See Localization for the full JSON structure and field reference.