quadlet-migrator-skill/references/validation.md

Validation

Use this file when the user asks how to verify or troubleshoot generated Quadlet units.

Basic deployment flow

1. Review the generated files in the current working directory and confirm the expected Quadlet units, env files, helper scripts, and required repo-local support files exist.
2. Run install.sh to copy only the reviewed unit files into the target Quadlet directory and place required runtime support files into the correct host-side paths.
3. Run the appropriate reload command.
4. Start the relevant units and inspect their status.
5. If needed, run uninstall.sh to remove the installed reviewed artifact set before regenerating or abandoning the deployment.

If the user requested an alternate apply script name explicitly, substitute that name where needed, but treat install.sh as the default documentation path.

Rootless

systemctl --user daemon-reload
systemctl --user start <unit>
systemctl --user status <unit>

Rootful

systemctl daemon-reload
systemctl start <unit>
systemctl status <unit>

Generator debugging

Use the Podman systemd generator dry run when units fail to appear or options look unsupported.

/usr/lib/systemd/system-generators/podman-system-generator --dryrun

For rootless debugging:

/usr/lib/systemd/system-generators/podman-system-generator --user --dryrun

Systemd verification

systemd-analyze verify <unit>.service

For user units:

systemd-analyze --user verify <unit>.service

Support-file and env checks

Before calling the result runnable, verify that:

• every referenced EnvironmentFile= exists at the installed path
• required env keys are actually present in the final env sources
• bind-mounted files and directories exist after installation
• repo-local entrypoint or helper scripts referenced by the container exist and are executable when needed
• initialization assets such as init.sql, seeds, bootstrap files, or config templates are present where the deployment expects them

Runnable-output gate checklist template:

• the support-file set is complete
• env completeness check passed against the actual final env sources
• unit files are installed in the intended Quadlet directory
• support files are installed at the host-side runtime paths expected by mounts and scripts
• service-management scripts operate on the same artifact set that was reviewed
• no required support file, env key, or typo-suspect mismatch remains unresolved

Do not call the result runnable until every item above is checked.

Common failure causes

• unsupported Quadlet option for the installed Podman version
• bind-mount source directory missing
• files were generated but install.sh has not yet copied the unit files into the target rootless or rootful unit directory and the required runtime support files into their host-side paths
• wrong rootless or rootful apply target directory
• unresolved env file path
• required env key missing from the final env file
• likely env-key typo or mismatch between source docs and final env output
• required repo-local config, init assets, or helper scripts missing from the installed artifact set
• permissions on rootless bind mounts
• readiness assumptions hidden behind depends_on

Troubleshooting posture

When validation fails, report:

• what generated successfully
• what was applied successfully
• what failed to generate, apply, or start
• whether the issue is syntax, unsupported feature, path resolution, installation path, missing support files, missing env keys, or permissions

Relationship to execution phase

Validation belongs after the files are written in the execution phase and applied to a valid Quadlet directory and the correct host-side runtime paths.

Before execution, the skill should already have completed planning and finalize review with the user. Do not treat validation as a substitute for design review.