new-podman-role

name	new_podman_role
description	Scaffold a podman-backed homelab service role with the repo's helper roles, healthcheck, nginx site, homepage bookmark, and qemu verification.

New Podman Service Role

Scaffold one container-backed service role. AGENTS.md is the source of truth; mirror nearby roles before inventing structure.

Required Facts

Collect or infer these before writing files:

• Service name: underscores, not hyphens.
• Canonical image reference and tag. If pinned, put the version/URL/hash in group_vars/all/versions.yml, not role vars.
• Published loopback port. Check both service_ports: and existing 127.0.0.1: literals before allocating.
• Nginx subdomain and homepage label/icon.
• Required site bind mounts: services, scratch, media, data, brumath, eckwersheim, or minio.
• Secrets and injection mode.
• Healthcheck command, verified against the image.

Ask only for facts that are real domain choices or cannot be proven from the repo. Do not invent secret boundaries.

Files

• roles/<svc>/tasks/main.yml: assert required inputs, create the service user, create podman secrets, install config with backup: true, register the nginx site, install the unit, then start/restart it through systemd_unit. Do not use handlers.
• roles/<svc>/templates/<svc>.service.j2: system-scope podman unit with the canonical image name, explicit user mapping, published loopback port, bind-mount gates, secrets, and --health-cmd plus --health-startup-cmd.
• roles/<svc>/tasks/_verify.yml: functional qemu checks. Probe the published port, the nginx vhost, health, and ownership of writable bind mounts.
• Cross-role wiring: service_ports, site.yml, and roles/homepage/templates/bookmarks.yaml.j2.

Required service inputs belong in host_vars or group_vars plus an assert. Optional host-overridable values may live in defaults/main.yml.

Podman Choices

• User: default to --user {{ <svc>_user.uid }}:{{ <svc>_user.gid }}. Use linuxserver PUID/PGID for linuxserver images; use fake-root uidmaps only when the image truly requires in-container root.
• Secrets: prefer app-native *_FILE, then linuxserver FILE__<VAR>, then type=env,target=VAR.
• Healthcheck: prefer service-native CLI, then existing curl/wget, then Python urllib.request in JSON-array argv form.
• --init: add only when the image runs the app directly as PID 1. Skip images that already use s6, tini, dumb-init, or an entrypoint that execs a supervisor.
• Networking: co-located containers should use <name>.dns.podman, not host ports or hard-coded IPs.

Verification

Run the narrow role test first:

test/testrole.py <svc>

Use --machine lab or --machine pug only when the role needs a producer-side layout that the default box fixture cannot model.

Before finishing, run the relevant lint target and inspect the diff for unnecessary role vars, pass-through inputs, missing backups, missing healthchecks, and stat-only verification.