new-podman-role

star 7

Scaffold a new podman-based service role following the homelab repo conventions. Use when adding a new self-hosted service that runs as a container — sets up service_user, podman_secret, systemd_unit helper invocations, healthcheck per the four-tier preference, nginx subdomain + homepage bookmark, and a `_verify.yml` exercising the live service.

adrienkohlbecker By adrienkohlbecker schedule Updated 6/10/2026
play_arrow Run Skill in Manus View GitHub

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.group }}. 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.

Install via CLI
npx skills add https://github.com/adrienkohlbecker/homelab --skill new-podman-role
Repository Details
star Stars 7
call_split Forks 1
navigation Branch main
article Path SKILL.md
More from Creator
adrienkohlbecker
adrienkohlbecker Explore all skills →