Contributing

Submit a template

Templates live in the getlawn/templates repository. This page covers the conventions and requirements for contributing a new template via pull request.

Naming Conventions

App ID — Lowercase, hyphen-separated. Must match the directory name and the id field in manifest.yaml. Use the app's commonly known name (e.g., paperless-ngx, uptime-kuma, adguard-home).

Compose filename. Use lawn-compose/compose.yaml.

Icon Requirements

Local icon files are optional when you use hosted artwork or an SF Symbol fallback. To bundle artwork, include an icon.svg (preferred), icon.png, icon.heif, or icon.pdf in the template directory. For PNG, use at least 256×256 pixels.

The required symbolFallback field in manifest.yaml names an SF Symbol used when no icon image is available. Use iconURL for hosted artwork and iconIsTemplate: true for a monochrome icon that adopts the foreground color. See the artwork reference.

Style Guidelines

• Localization — Compose configuration and extension strings (display names, descriptions, labels, notice titles) belong in locales/en.json. App names, taglines, and descriptions remain in manifest.yaml.
• Notices — Use a maximum of 2-3 per template. Reserve them for information users genuinely need to act on: login credentials, required setup steps, or warnings about values they should not change. Use info for general guidance and warning for critical actions.
• Environment values — Use required-value expressions such as ${POSTGRES_PASSWORD:?POSTGRES_PASSWORD is required} for secrets. Use ${VAR:-default} for nonsensitive defaults, and supply disposable secrets explicitly for standalone docker compose config checks.
• Descriptions — Write clear, concise descriptions for variables and environment metadata. Describe what the value controls, not just what it is.
• Display ordering — Use weight to order config variables logically. Group related settings together and put important ones first.
• Volumes — Use relative paths (./data:/app/data) for persistent data. Avoid absolute paths unless strictly necessary.

PR Checklist

These requirements apply to submissions to the official catalog. Custom catalogs use the runtime manifest format, where tagline, category, and compatibility metadata are optional.

Before submitting a template, verify each item:

Manifest

• id matches the directory name
• name, tagline, description, symbolFallback, and category are set
• compatibility.minLawnVersion is set
• category is one of: Documents, Media, Development, Networking, Utilities, Databases, Monitoring
• webPort is set if the app has a web UI
• At least one link (GitHub or documentation) is included

Compose File

• x-lawn.compatibility.minLawnVersion is set in every compose file
• All images use explicit version tags (no latest)
• Compose syntax check passes with disposable variable values and no missing-variable warnings
• Secret substitutions fail on unset or empty values with ${VAR:?error}; nonsensitive values may use ${VAR:-default}
• Volumes use relative paths for persistent data
• Ports are declared for services with a web UI

Variables and Secrets

• Passwords and tokens use generatedSecret or user-provided values, without hardcoded defaults
• Generated secrets declare the appropriate format and use length or bytes as required
• userProvided variables hold values users supply, with required: true when a value is needed to start
• inputType is set for boolean and number config variables
• Config options use compose overlays for each selectable value

Localization

• locales/en.json exists with entries for Compose configuration and extension strings
• Every config variable has displayName and description
• Every config option value has a label
• Boolean config variables have exactly 2 option labels ("true" and "false")
• Every environment variable has a description
• Every health check has a description
• Every notice has a title and all elements have label/content
• No dangling keys (JSON entries without matching YAML structures)

Health Checks

• At least one Lawn health check (x-lawn.healthChecks) is defined for the main service
• HTTP checks use a reliable endpoint (health or root path)
• Database services have a standard healthcheck in the compose spec

Notices

• Login credentials are surfaced in a notice (if applicable)
• Notices use type: field with source for dynamic values instead of hardcoding passwords
• No more than 2-3 notices per template

Testing

• Localization review finds no missing or dangling entries
• Install a disposable instance from a local catalog using a qualified template ID
• Complete required configuration, start the app, and confirm its health checks pass
• Perform a real app action and verify its data survives a stop and start
• Remove the disposable instance and local catalog registration after testing

lawn template validate and lawn template test are planned and are not available in the current release.