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.
This commit is contained in:
tanshu committed 2026-10-18 22:10:57 +05:30
1 parent 2aab1aec1e
commit 476a6d7cd0
85 files changed
+372 -2433

No files matched your search

+6 -45
View File
@@ -1,45 +1,12 @@
---
# Attach a service's network to Postgres.
#
# Postgres is the *base* unit and knows nothing about its clients, the same way
# Caddy knows nothing about its upstreams. A service that needs a database adds
# itself by dropping files next to postgres.container, and Quadlet merges them in.
#
# Include this from a service playbook:
#
# - name: Attach this service to Postgres
# ansible.builtin.include_tasks: "{{ playbook_dir }}/../postgres/roles/attach/tasks/main.yaml"
# vars:
# network_name: "{{ network_name }}"
#
# The including play must:
#
# 1. have created {{ network_name }}.network already — caddy/roles/register
# does that, and every service here that needs a database is also behind
# Caddy, so its register include comes first;
# 2. run the `podman` role (or include its task file and define the same four
# vars), for podman_user and quadlet_dir;
# 3. define a "Restart Postgres" handler — see
# roles/postgres/handlers/main.yaml for the exact snippet; and
# 4. flush handlers before starting the app, on a first attach. This include
# notifies that restart, so by default it runs at the end of the play —
# after the app has already started and failed to resolve `db`. A
# `meta: flush_handlers` immediately after this include is enough; see
# tandoor/roles/postgres for the working example.
#
# It runs as the connection user, which must be the rootless podman_user.
#
# A service may instead write these two files from its own role; the bytes have
# to match this file exactly, or the two will overwrite each other on every run.
- name: "Check that the {{ network_name }} network unit exists"
ansible.builtin.stat:
path: "{{ quadlet_dir }}/{{ network_name }}.network"
register: postgres_attach_network
# A drop-in naming a .network file that does not exist makes Quadlet fail to
# generate the whole postgres unit, with a message that does not mention the
# drop-in at all. Fail here instead, where the cause is obvious.
# A drop-in naming a missing network breaks unit generation with an unrelated
# error, so fail here instead.
- name: "Fail if {{ network_name }} has no network unit"
ansible.builtin.assert:
that: postgres_attach_network.stat.exists
@@ -64,20 +31,14 @@
group: "{{ podman_user }}"
mode: '0644'
content: |
# Added by the {{ network_name }} playbook. Do not edit by hand.
#
# Deleting this file removes the network from {{ postgres_container | default('postgres') }} on
# the next daemon-reload; nothing else changes.
# Added by {{ network_name }}. Deleting it detaches the network from
# {{ postgres_container | default('postgres') }} on the next daemon-reload.
[Container]
Network={{ network_name }}.network
notify: Restart Postgres
# NetworkAlias= applies to every network the container joins, which is exactly
# right for a hub: every app in this repo reaches postgres as `db` (nextcloud,
# gitea, tandoor and outline use the alias; the rest use the container name).
# It is a fixed value in one shared file, not a per-service option, so the same
# bytes are written no matter how many services attach — two services writing
# their own aliases would make Quadlet pass --network-alias twice.
# NetworkAlias applies to every network, so one shared file holds the fixed
# alias. Two services writing their own would pass --network-alias twice.
- name: "Give {{ postgres_container | default('postgres') }} the shared 'db' alias"
ansible.builtin.copy:
dest: >-