Testing

Test your template

Test your template with the installed Lawn app and CLI. Start with a Docker Compose syntax check, then verify the app in Lawn.

Add a local catalog

Open Lawn and install the CLI. Put your template in a local catalog with this structure, replacing my-app with its manifest ID:

lawn-template-check/
└── my-app/
    ├── manifest.yaml
    ├── locales/
    │   └── en.json
    └── lawn-compose/
        └── compose.yaml

Include any icon and init files your template uses. The catalog path points to the folder containing the app folders, not to an individual template.

lawn catalog add ~/Projects/lawn-template-check
lawn --output json catalog list
lawn catalog info lawn-template-check/my-app

Find the entry with your local folder's URL in the JSON output and check its slug. The examples use lawn-template-check, the lowercase folder name. If your slug differs, replace it in the commands below. The qualified ID selects your local copy even when another catalog contains my-app.

Check that the catalog entry shows the expected name, description, and icon. If the app is absent or these are wrong, check its manifest before installing.

Install a disposable instance

Choose an instance name that does not already appear in lawn app list. This example uses my-app-template-check and lets Lawn choose available ports:

lawn app list
lawn app install lawn-template-check/my-app --name my-app-template-check --random-port

Wait for installation to finish. Open this instance in Lawn and check the generated settings, translated labels, options, and notices against your template and localization file.

Templates with required variables

source: userProvided makes a setting editable; it does not make the setting required. Startup is blocked only when an active setting declares required: true and its value is missing or an empty string. Settings in unselected config options do not block startup.

After installing an app with missing required settings, complete Edit Configuration, save, then click Start. Verify that starting without a required value reports the missing setting, and that supplying it allows startup. An empty optional userProvided setting should not produce a missing-required-setting error.

See Required values for defaults and config option requirements. You can also inspect and set template settings with the CLI:

lawn app config list my-app-template-check

For example, if your template declares ADMIN_PASSWORD, supply a disposable test value:

lawn app config set my-app-template-check ADMIN_PASSWORD=disposable-test-password

Start and use the app

Click Start in Lawn, or run:

lawn app start my-app-template-check
lawn app info my-app-template-check

Confirm that startup finishes and the template's health checks pass. For an app with a web interface, open the URL shown by Lawn and complete a real action, such as uploading a named test file or creating a record you can identify later. Check any credential notices against the credentials the app actually accepts. A passing health check alone does not prove the app works.

Inspect failures with:

lawn app logs my-app-template-check

For apps without a web interface, connect with the app's normal client and perform an equivalent action.

Verify persistence and configuration choices

Stop and start the instance, then check that the file or record you created is still present:

lawn app stop my-app-template-check
lawn app start my-app-template-check

If the app stores no persistent data, verify its normal response after restarting instead. Verify that credentials still work and settings remain as saved. Test each configuration option that changes the services or their behavior, including its localized label and any required setup.

Clean up and retest

Remove only the disposable instance, then remove the local catalog registration:

lawn app stop my-app-template-check
lawn app remove my-app-template-check
lawn catalog remove ~/Projects/lawn-template-check

Removing the instance deletes its data. Removing the catalog registration leaves your template folder on disk.

After editing the template, repeat this workflow to register the local catalog and install a fresh disposable instance. Editing a template does not rewrite an already installed instance.