Cut the comment bloat from the Podman playbooks

Comment blocks now stay within three lines and explain only the non-obvious. Long histories, include examples, and commented-out code are gone. No task, key, or value changed; the only data change is comment text inside the generated unit files.

caddy/roles/caddy/handlers/main.yaml

@@ -1,6 +1,4 @@
 ---
-# All handlers run as the connection user ({{ podman_user }}), so systemctl
-# --user works without setting XDG_RUNTIME_DIR.
 
 - name: Reload systemd user units
   ansible.builtin.command: systemctl --user daemon-reload
@@ -15,15 +13,7 @@
     daemon_reload: true
   listen: Restart Caddy
 
-# Reference implementation for service playbooks. A service that appends a site
-# block to {{ caddyfile_path }} should notify this instead of restarting the
-# container, and defines its own copy of the handler in its caddy role, e.g.:
-#
-#   - name: Reload Caddy configuration
-#     ansible.builtin.command: podman exec {{ caddy_name }} caddy reload --config /etc/caddy/Caddyfile
-#     listen: "Reload Caddy"
-#
-# Note the container path is /etc/caddy/Caddyfile (the mount), not caddyfile_path.
+# The container path is the mount, /etc/caddy/Caddyfile, not caddyfile_path.
 - name: Reload Caddy configuration
   ansible.builtin.command: >-
     podman exec {{ caddy_name }}

caddy/roles/caddy/tasks/main.yaml

@@ -1,9 +1,4 @@
 ---
-# Start Caddy
-#
-# Everything here runs as {{ podman_user }} — the connection user. No become,
-# no XDG_RUNTIME_DIR: SSH gave us a real PAM session, so systemd's user manager
-# is reachable via the standard environment.
 
 - name: Ensure Caddy directories exist
   ansible.builtin.file:
@@ -23,13 +18,8 @@
     path: "{{ caddyfile_path }}"
   register: caddyfile_stat
 
-# Caddy exits 1 with a bare "EOF" on an empty config file, so an empty
-# Caddyfile means caddy.service crash-loops. Seed a minimal valid config.
-#
-# Only acts when the file is missing or still empty, so it never fights the
-# site blocks that service playbooks append via blockinfile. The global
-# options block must come first, which is why it is seeded rather than
-# appended.
+# Caddy exits 1 on an empty config file, so it needs a valid one first.
+# The global options block has to come before any site block.
 - name: Seed the Caddyfile with a valid empty config
   ansible.builtin.copy:
     dest: "{{ caddyfile_path }}"
@@ -72,9 +62,7 @@
         state: started
         daemon_reload: true
   rescue:
-    # systemd reports "control process exited with error code" and nothing
-    # else, which is useless for the usual failures (a port already bound, a
-    # missing image, a bad volume). Pull the real reason out.
+    # systemd only reports a generic exit code, so collect the real reason.
     - name: Collect Caddy diagnostics
       ansible.builtin.command: "{{ item }}"
       loop:
@@ -92,8 +80,7 @@
       ansible.builtin.fail:
         msg: "Caddy did not start — see the diagnostics above."
 
-# Quadlet honours [Install] WantedBy= when it generates the unit, so
-# `systemctl enable` is neither needed nor possible on a generated unit.
+# Quadlet honours [Install] WantedBy=, so generated units cannot be enabled.
 - name: Verify Caddy is running
   ansible.builtin.command: "systemctl --user is-active {{ caddy_unit }}"
   register: caddy_active

caddy/roles/podman/tasks/main.yaml

@@ -1,9 +1,4 @@
 ---
-# Rootless Podman prerequisites. Shared by every container playbook.
-#
-# This playbook runs AS the container user; it does not use become to reach it.
-# Root-only steps elevate individually. Keeping the connection's PAM session
-# intact is what lets `systemctl --user` work without setting XDG_RUNTIME_DIR.
 
 - name: Fail if the connecting user resolved to root
   ansible.builtin.assert:
@@ -20,34 +15,21 @@
   ansible.builtin.apt:
     name:
       - podman
-      # Everything below is only a Recommends, not a Depends, of podman or
-      # netavark. apt installs Recommends by default, so these would normally
-      # arrive on their own; listing them makes the requirement explicit and
-      # keeps it true under --no-install-recommends.
-      # - aardvark-dns   # container-name DNS: Caddy resolves every upstream by name
-      # - nftables       # netavark's firewall backend; Podman 6 dropped iptables
-      # - passt          # pasta, the rootless network backend
-      # - uidmap         # newuidmap/newgidmap, required for rootless user namespaces
     state: present
     update_cache: true
     cache_valid_time: 3600
   become: true
 
-# Without lingering, the user's systemd manager is torn down when the last
-# session ends: Quadlet units stop, and they never start at boot.
+# Without lingering, the user manager stops with the last session and units
+# never start at boot.
 - name: Enable systemd lingering for {{ podman_user }}
   ansible.builtin.command: "loginctl enable-linger {{ podman_user }}"
   args:
     creates: "/var/lib/systemd/linger/{{ podman_user }}"
   become: true
 
-# Rootless containers cannot bind host ports below 1024 unless the kernel
-# floor is lowered. Caddy publishes 80/443.
-#
-# This is applied inline rather than via a handler on purpose: handlers only
-# run at the end of the play, by which point Caddy has already tried (and
-# failed) to bind port 80. sysctl -w touches the running kernel; the file
-# makes it survive a reboot.
+# Rootless containers cannot bind ports below 1024 unless the kernel floor is
+# lowered. Applied inline, because a handler would run after Caddy already bound.
 - name: Read the current unprivileged port floor
   ansible.builtin.command: sysctl -n net.ipv4.ip_unprivileged_port_start
   register: podman_port_floor

caddy/roles/register/tasks/main.yaml

@@ -1,33 +1,6 @@
 ---
-# Register a service's logical network with Caddy.
-#
-# Caddy is the *base* unit and knows nothing about its upstreams. Each service
-# adds itself by writing two files into the Quadlet directory:
-#
-#   1. its own <name>.network unit, and
-#   2. a drop-in next to caddy.container that pulls that network into Caddy.
-#
-# Caddy's own playbook never changes when a service is added or removed.
-#
-# Include this from a service playbook:
-#
-#   - name: Register this service with Caddy
-#     ansible.builtin.include_tasks: "{{ playbook_dir }}/../caddy/roles/register/tasks/main.yaml"
-#     vars:
-#       network_name: "{{ container_name }}"
-#
-# The including play must also run the `podman` role (for podman_user and
-# quadlet_dir) and define a "Restart Caddy" handler:
-#
-#   - name: Restart Caddy
-#     ansible.builtin.systemd_service:
-#       name: caddy.service
-#       scope: user
-#       state: restarted
-#       daemon_reload: true
-#     listen: Restart Caddy
-#
-# It runs as the connection user, which must be {{ podman_user }}.
+# Include from a service playbook with network_name set. The play must define
+# the "Restart Caddy" handler.
 
 - name: "Create the {{ network_name }} network unit"
   ansible.builtin.copy:
@@ -36,15 +9,8 @@
     group: "{{ podman_user }}"
     mode: '0644'
     content: |
-      # {{ network_name }} — logical app network.
-      # Managed by Ansible. Do not edit by hand.
-      #
-      # NetworkName pins the Podman network name. Without it Quadlet would
-      # create "systemd-{{ network_name }}".
-      #
-      # isolate blocks traffic between separate Podman networks, so a container
-      # on this network cannot reach one that is only on another. Caddy and any
-      # shared service still reach it, because they are members of it.
+      # Managed by Ansible. NetworkName pins the Podman name; isolate blocks
+      # traffic between separate networks.
       [Network]
       NetworkName={{ network_name }}_net
       Options=isolate=true
@@ -57,10 +23,8 @@
     group: "{{ podman_user }}"
     mode: '0644'
     content: |
-      # Added by the {{ network_name }} playbook. Do not edit by hand.
-      #
-      # Quadlet merges this into caddy.container. Deleting this file removes
-      # the network from Caddy on the next daemon-reload.
+      # Added by {{ network_name }}. Deleting it detaches the network from
+      # Caddy on the next daemon-reload.
       [Container]
       Network={{ network_name }}.network
   notify: Restart Caddy