docs(roles): add argument_specs and README for traefik, authentik, drawio, garage, nextcloud

Each of the five roles touched in this branch now ships:

* meta/argument_specs.yml: typed schema for every variable in
  defaults/main.yml plus the optional inputs surfaced via this
  branch (traefik_extra_hosts, authentik_host_rewrite_domains,
  authentik_proxy_apps.mode / .allowed_groups, drawio_extra_domains,
  drawio_authentik_forward_auth*, garage_webui_authentik_forward_auth*).
  All five specs load cleanly through ansible-core's
  ArgumentSpecValidator.

* README.md: replaces the ansible-galaxy boilerplate (where it was
  still in place) with a focused write-up — service vars, required
  secrets, ForwardAuth/idempotency notes, dependencies, and a working
  example playbook. authentik and garage READMEs are rewritten to cover
  the new knobs while preserving their existing content.

roles/authentik/README.md

@@ -1,28 +1,131 @@
 # Authentik
 
-Deploys Authentik identity provider with Docker Compose.
+Deploys [authentik](https://goauthentik.io) (server + worker + Postgres)
+as a Docker Compose stack behind Traefik, with all resources provisioned
+via templated blueprints.
+
+## What this role does
+
+- Renders the Compose stack with traefik labels and an optional
+  split-horizon host rewrite (see below)
+- Provisions local users, groups, OIDC apps, Proxy/ForwardAuth apps,
+  LDAP apps and outposts, and Entra ID OAuth sources via blueprints
+- Configures the login screen (visible sources, local login fields)
+- Supports declarative cleanup via `authentik_removed_*` lists
 
 ## Variables
 
-See `defaults/main.yml` for all available variables.
+Full spec with types and defaults: `meta/argument_specs.yml`. The most
+common overrides:
 
-## Blueprints
+### Service
+
+- `authentik_domains` (required, list): FQDNs the router accepts. First
+  entry is the canonical hostname; further entries cover internal
+  `*.int.*` names for server-to-server traffic.
+- `authentik_secret_key` (required): PG fernet / signing secret.
+  Generate with `openssl rand -base64 60`.
+- `authentik_postgres_password` (required).
+- `authentik_image`, `authentik_port`, `authentik_log_level`.
+
+### Split-horizon host rewrite
+
+`authentik_host_rewrite_domains` lists hostnames that should reach the
+authentik container but make it generate URLs (OIDC issuer, password
+reset links, etc.) as if the request had arrived on
+`authentik_domains[0]`.
+
+For each entry the role:
+
+- Creates a dedicated traefik router on that hostname
+- Routes it to a URL-based loadbalancer service that disables
+  `passHostHeader`, so the upstream Host header becomes the canonical
+  FQDN
+- Pins `X-Forwarded-Host` via middleware so the iss claim stays aligned
+  with the public hostname browsers see
+
+Use case: an internal `auth.int.example.com` keeps server-to-server
+traffic in the LAN, but Keycloak/Nextcloud/etc. still receive issuer
+URLs matching `auth.example.com`.
+
+### Blueprints
 
 The role renders blueprints for:
+
 - Local users (`authentik_local_users`)
+- Groups (`authentik_groups`)
 - OIDC applications (`authentik_oidc_apps`)
 - Proxy applications (`authentik_proxy_apps`)
 - Proxy outposts (`authentik_proxy_outposts`)
+- LDAP applications (`authentik_ldap_apps`)
+- LDAP outpost (`authentik_ldap_outpost`)
 - Entra ID sources (`authentik_entra_sources`)
-- Login screen sources (`authentik_login_source_ids`)
+- Login-screen source visibility (`authentik_login_sources`)
 
-Secrets are passed via `authentik_blueprint_env` using environment variable references.
+Secrets are passed via the `authentik_blueprint_env` env-var indirection
+so they never land in rendered blueprint YAML on disk.
+
+#### Proxy apps: mode and group restrictions
+
+Each entry in `authentik_proxy_apps` supports:
+
+- `mode` (default `forward_single`): one of `proxy`, `forward_single`,
+  `forward_domain`
+- `allowed_groups`: when set, a `PolicyBinding` is emitted per group on
+  the application. authentik OR-evaluates bindings, so users in any
+  listed group pass and users in none are denied.
+
+Example:
+
+```yaml
+authentik_proxy_apps:
+  - slug: drawio
+    name: drawio
+    external_host: "https://drawio.example.com"
+    mode: forward_single
+    allowed_groups:
+      - drawio-users
+      - admins
+```
 
 ## Removing resources
 
-To remove resources from Authentik, move slugs to the removal lists:
+Move slugs from the active list to the matching removal list:
+
 - `authentik_removed_oidc_apps`
 - `authentik_removed_proxy_apps`
 - `authentik_removed_local_users`
 
-After confirming deletion, remove the slug from the list.
+After authentik has applied the deletion blueprint, remove the slug
+from the list to keep state clean.
+
+## Dependencies
+
+- Traefik network (`authentik_traefik_network`, default `proxy`)
+- Internal backend network (`authentik_backend_network`, default `backend`)
+
+## Example playbook
+
+```yaml
+- hosts: identity_servers
+  roles:
+    - role: digitalboard.core.authentik
+      vars:
+        authentik_domains:
+          - "auth.example.com"
+          - "auth.int.example.com"
+        authentik_host_rewrite_domains:
+          - "auth.int.example.com"
+        authentik_secret_key: "{{ vault_authentik_secret_key }}"
+        authentik_postgres_password: "{{ vault_authentik_pg_password }}"
+        authentik_proxy_apps:
+          - slug: drawio
+            name: drawio
+            external_host: "https://drawio.example.com"
+            mode: forward_single
+            allowed_groups: [drawio-users]
+```
+
+## License
+
+MIT-0

roles/authentik/defaults/main.yml

@@ -12,7 +12,20 @@ authentik_docker_compose_dir: "{{ docker_compose_base_dir }}/{{ authentik_servic
 authentik_docker_volume_dir: "{{ docker_volume_base_dir }}/{{ authentik_service_name }}"
 
 # Authentik service configuration
-authentik_domain: "authentik.local.test"
+# FQDNs the authentik router accepts. The first entry is the canonical
+# domain; further entries cover internal *.int.* names used for
+# server-to-server traffic so backend calls don't hairpin via DMZ.
+authentik_domains:
+  - "authentik.local.test"
+
+# Hostnames that should reach authentik but make it generate URLs (OIDC
+# issuer, password reset links, etc.) as if requested from the canonical
+# `authentik_domains[0]` instead. Used for split-horizon setups where an
+# internal FQDN (e.g. `auth.int.example.com`) keeps server-to-server
+# traffic in the LAN but the iss claim must still match the public
+# hostname that browsers see. Traefik handles each entry via a separate
+# router that rewrites the Host header before forwarding to authentik.
+authentik_host_rewrite_domains: []
 authentik_image: "ghcr.io/goauthentik/server:2026.2.2"
 authentik_port: 9000
 authentik_secret_key: "changeme-generate-a-random-string"

roles/authentik/meta/argument_specs.yml

@@ -0,0 +1,193 @@
+---
+argument_specs:
+  main:
+    short_description: Deploy authentik (server + worker + Postgres) via Docker Compose.
+    description:
+      - Renders a Compose stack for authentik with traefik labels, optional
+        TLS and a configurable split-horizon host-rewrite that keeps the OIDC
+        issuer URL on the canonical public hostname even when traffic enters
+        on an internal FQDN.
+      - Provisions resources through templated blueprints
+        (local users, groups, OIDC/Proxy/LDAP apps, outposts, OAuth sources).
+    options:
+      docker_compose_base_dir:
+        type: path
+        default: /etc/docker/compose
+      docker_volume_base_dir:
+        type: path
+        default: /srv/data
+      authentik_service_name:
+        type: str
+        default: authentik
+      authentik_docker_compose_dir:
+        type: path
+        description: Defaults to C({{ docker_compose_base_dir }}/{{ authentik_service_name }}).
+      authentik_docker_volume_dir:
+        type: path
+        description: Defaults to C({{ docker_volume_base_dir }}/{{ authentik_service_name }}).
+
+      authentik_domains:
+        type: list
+        elements: str
+        required: true
+        description:
+          - FQDNs the authentik router accepts. The first entry is the
+            canonical (public) hostname and is used for the network alias,
+            the X-Forwarded-Host rewrite target, and as the default OIDC
+            issuer. Further entries cover internal C(*.int.*) names used
+            for server-to-server traffic.
+      authentik_host_rewrite_domains:
+        type: list
+        elements: str
+        default: []
+        description:
+          - Hostnames that should reach authentik but make it generate URLs
+            (OIDC issuer, password reset links, etc.) as if the request had
+            arrived on C(authentik_domains[0]).
+          - Each entry gets its own traefik router and a URL-based
+            loadbalancer service that disables passHostHeader and pins
+            X-Forwarded-Host via middleware. Used for split-horizon setups
+            where the LAN keeps server-to-server traffic but the iss claim
+            must match the public hostname browsers see.
+      authentik_image:
+        type: str
+        default: ghcr.io/goauthentik/server:2026.2.2
+      authentik_port:
+        type: int
+        default: 9000
+      authentik_secret_key:
+        type: str
+        required: true
+        description: PG fernet key / signing secret. Generate with C(openssl rand -base64 60).
+
+      authentik_postgres_image:
+        type: str
+        default: postgres:16-alpine
+      authentik_postgres_db:
+        type: str
+        default: authentik
+      authentik_postgres_user:
+        type: str
+        default: authentik
+      authentik_postgres_password:
+        type: str
+        required: true
+
+      authentik_traefik_network:
+        type: str
+        default: proxy
+      authentik_backend_network:
+        type: str
+        default: backend
+      authentik_use_ssl:
+        type: bool
+        default: true
+
+      authentik_log_level:
+        type: str
+        choices: [trace, debug, info, warning, error]
+        default: info
+      authentik_error_reporting_enabled:
+        type: bool
+        default: false
+
+      authentik_proxy_apps:
+        type: list
+        elements: dict
+        default: []
+        description:
+          - Proxy/ForwardAuth applications rendered via the
+            C(blueprint-proxy-app.yaml.j2) template.
+        options:
+          slug:
+            type: str
+            required: true
+          name:
+            type: str
+            required: true
+          internal_host:
+            type: str
+            description: Required when C(mode=proxy).
+          external_host:
+            type: str
+            required: true
+          mode:
+            type: str
+            choices: [proxy, forward_single, forward_domain]
+            default: forward_single
+            description:
+              - "C(proxy): the outpost itself proxies traffic to internal_host."
+              - "C(forward_single): a single app behind an external reverse
+                proxy via ForwardAuth."
+              - "C(forward_domain): wildcard mode — one provider guards every
+                host on a cookie domain."
+          allowed_groups:
+            type: list
+            elements: str
+            description:
+              - If set, PolicyBindings are emitted (one per group, OR-evaluated).
+                Users in none of the listed groups are denied.
+          skip_path_regex:
+            type: str
+          flows:
+            type: dict
+            description: Authentication / authorization / invalidation flow slugs.
+
+      authentik_proxy_outposts:
+        type: list
+        elements: dict
+        default: []
+
+      authentik_ldap_apps:
+        type: list
+        elements: dict
+        default: []
+      authentik_ldap_outpost:
+        type: dict
+        default: {}
+
+      authentik_oidc_apps:
+        type: list
+        elements: dict
+        default: []
+
+      authentik_entra_sources:
+        type: list
+        elements: dict
+        default: []
+      authentik_login_sources:
+        type: list
+        elements: dict
+        default: []
+      authentik_identification_stage_name:
+        type: str
+        default: default-authentication-identification
+      authentik_login_user_fields:
+        type: list
+        elements: str
+        choices: [username, email, upn]
+        default: [username, email]
+        description: Local login fields shown on the login screen. Empty list hides local login.
+
+      authentik_groups:
+        type: list
+        elements: dict
+        default: []
+      authentik_local_users:
+        type: list
+        elements: dict
+        default: []
+
+      authentik_removed_oidc_apps:
+        type: list
+        elements: str
+        default: []
+        description: OIDC application slugs scheduled for deletion.
+      authentik_removed_proxy_apps:
+        type: list
+        elements: str
+        default: []
+      authentik_removed_local_users:
+        type: list
+        elements: str
+        default: []

roles/authentik/templates/blueprints/blueprint-login-sources.yaml.j2

@@ -16,8 +16,10 @@ entries:
 {% for field in authentik_login_user_fields %}
         - {{ field }}
 {% endfor %}
+{% if authentik_login_sources %}
       # OAuth/social login sources (use !Find to reference sources from other blueprints)
       sources:
 {% for src in authentik_login_sources %}
         - !Find [authentik_sources_oauth.oauthsource, [slug, {{ src.slug }}]]
 {% endfor %}
+{% endif %}

roles/authentik/templates/blueprints/blueprint-proxy-app.yaml.j2

@@ -20,6 +20,16 @@ entries:
 
       internal_host: "{{ item.internal_host }}"
       external_host: "{{ item.external_host }}"
+{# Provider mode controls how authentik treats the proxy app:
+   - proxy          : the outpost itself proxies traffic to internal_host
+   - forward_single : a single app behind an external reverse proxy
+                      (traefik forwardauth talks to authentik per-domain)
+   - forward_domain : wildcard mode — one provider guards every host on a
+                      cookie domain; configure forward_auth_mode=domain on
+                      the outpost in that case. Default to forward_single
+                      since that's the common ForwardAuth-with-traefik
+                      pattern. #}
+      mode: {{ item.mode | default('forward_single') }}
 
 {% if item.skip_path_regex is defined and item.skip_path_regex|length > 0 %}
       skip_path_regex: |
@@ -34,3 +44,20 @@ entries:
       name: "{{ item.name | default(item.slug) }}"
       slug: {{ item.slug }}
       provider: !KeyOf proxy-provider-{{ item.slug }}
+
+{% if item.allowed_groups is defined and item.allowed_groups | length > 0 %}
+{# Restrict access to listed groups: one PolicyBinding per group, all bound
+   to the application. Authentik treats multiple bindings on the same target
+   as OR (a user matching any binding passes), and a request from a user in
+   none of the bound groups is denied. #}
+{%   for group_name in item.allowed_groups %}
+  - model: authentik_policies.policybinding
+    identifiers:
+      target: !KeyOf app-{{ item.slug }}
+      order: {{ loop.index0 }}
+      group: !Find [authentik_core.group, [name, "{{ group_name }}"]]
+    attrs:
+      enabled: true
+      negate: false
+{%   endfor %}
+{% endif %}

roles/authentik/templates/docker-compose.yml.j2

@@ -43,19 +43,57 @@ services:
       postgres:
         condition: service_healthy
     networks:
-      - {{ authentik_backend_network }}
-      - {{ authentik_traefik_network }}
+      {{ authentik_backend_network }}: {}
+      # Network alias so traefik (which shares this network) can resolve
+      # the canonical FQDN to this container directly. The URL-based
+      # service below uses that to send upstream traffic with a fixed
+      # Host header equal to the canonical hostname.
+      {{ authentik_traefik_network }}:
+        aliases:
+          - {{ authentik_domains[0] }}
     labels:
       - traefik.enable=true
       - traefik.docker.network={{ authentik_traefik_network }}
-      - traefik.http.routers.{{ authentik_service_name }}.rule=Host(`{{ authentik_domain }}`)
+      - traefik.http.routers.{{ authentik_service_name }}.rule={% for d in authentik_domains %}Host(`{{ d }}`){% if not loop.last %} || {% endif %}{% endfor +%}
+      - traefik.http.routers.{{ authentik_service_name }}.service={{ authentik_service_name }}
 {% if authentik_use_ssl %}
       - traefik.http.routers.{{ authentik_service_name }}.entrypoints=websecure
       - traefik.http.routers.{{ authentik_service_name }}.tls=true
+{% if traefik_cert_mode | default('selfsigned') == 'acme' %}
+      - traefik.http.routers.{{ authentik_service_name }}.tls.certresolver={{ traefik_ssl_cert_resolver | default('dns') }}
+{% endif %}
 {% else %}
       - traefik.http.routers.{{ authentik_service_name }}.entrypoints=web
 {% endif %}
       - traefik.http.services.{{ authentik_service_name }}.loadbalancer.server.port={{ authentik_port }}
+{% if authentik_host_rewrite_domains | length > 0 %}
+      # Server-to-server entry: a separate service points at this very
+      # container by the canonical FQDN (resolved via the network alias
+      # above) and disables passHostHeader so the upstream Host header
+      # becomes `{{ authentik_domains[0] }}`. Authentik builds OIDC issuer
+      # URLs from X-Forwarded-Host (not Host), so we also pin that header
+      # via middleware. Together this keeps the iss claim aligned with
+      # the public hostname browsers see during login, even when the
+      # request itself arrived on an internal *.int.* FQDN.
+      - traefik.http.services.{{ authentik_service_name }}-rewrite.loadbalancer.server.url=http://{{ authentik_domains[0] }}:{{ authentik_port }}
+      - traefik.http.services.{{ authentik_service_name }}-rewrite.loadbalancer.passhostheader=false
+      - traefik.http.middlewares.{{ authentik_service_name }}-xfh-rewrite.headers.customrequestheaders.X-Forwarded-Host={{ authentik_domains[0] }}
+{% for d in authentik_host_rewrite_domains %}
+      - traefik.http.routers.{{ authentik_service_name }}-rewrite-{{ loop.index0 }}.rule=Host(`{{ d }}`)
+      - traefik.http.routers.{{ authentik_service_name }}-rewrite-{{ loop.index0 }}.priority=100
+      - traefik.http.routers.{{ authentik_service_name }}-rewrite-{{ loop.index0 }}.service={{ authentik_service_name }}-rewrite
+      - traefik.http.routers.{{ authentik_service_name }}-rewrite-{{ loop.index0 }}.middlewares={{ authentik_service_name }}-xfh-rewrite
+{% if authentik_use_ssl %}
+      - traefik.http.routers.{{ authentik_service_name }}-rewrite-{{ loop.index0 }}.entrypoints=websecure
+      - traefik.http.routers.{{ authentik_service_name }}-rewrite-{{ loop.index0 }}.tls=true
+{% if traefik_cert_mode | default('selfsigned') == 'acme' %}
+      - traefik.http.routers.{{ authentik_service_name }}-rewrite-{{ loop.index0 }}.tls.certresolver={{ traefik_ssl_cert_resolver | default('dns') }}
+{% endif %}
+{% else %}
+      - traefik.http.routers.{{ authentik_service_name }}-rewrite-{{ loop.index0 }}.entrypoints=web
+{% endif %}
+{% endfor %}
+{% endif %}
 
   worker:
     image: {{ authentik_image }}

roles/collabora/defaults/main.yml

@@ -12,7 +12,11 @@ collabora_docker_compose_dir: "{{ docker_compose_base_dir }}/{{ collabora_servic
 collabora_docker_volume_dir: "{{ docker_volume_base_dir }}/{{ collabora_service_name }}"
 
 # Service configuration
-collabora_domain: "office.local.test"
+# FQDNs the collabora router accepts. The first entry is the canonical
+# domain; further entries cover internal *.int.* names used for
+# server-to-server WOPI discovery.
+collabora_domains:
+  - "office.local.test"
 collabora_image: "collabora/code:latest"
 collabora_port: 9980
 collabora_extra_hosts: []

roles/collabora/handlers/main.yml

@@ -5,4 +5,4 @@
 - name: restart collabora
   community.docker.docker_compose_v2:
     project_src: "{{ collabora_docker_compose_dir }}"
-    state: restarted
+    state: present

roles/collabora/templates/docker-compose.yml.j2

@@ -20,11 +20,14 @@ services:
     labels:
       - traefik.enable=true
       - traefik.docker.network={{ collabora_traefik_network }}
-      - traefik.http.routers.{{ collabora_service_name }}.rule=Host(`{{ collabora_domain }}`)
+      - traefik.http.routers.{{ collabora_service_name }}.rule={% for d in collabora_domains %}Host(`{{ d }}`){% if not loop.last %} || {% endif %}{% endfor +%}
       - traefik.http.services.{{ collabora_service_name }}.loadbalancer.server.port={{ collabora_port }}
 {% if collabora_use_ssl %}
       - traefik.http.routers.{{ collabora_service_name }}.entrypoints=websecure
       - traefik.http.routers.{{ collabora_service_name }}.tls=true
+{% if traefik_cert_mode | default('selfsigned') == 'acme' %}
+      - traefik.http.routers.{{ collabora_service_name }}.tls.certresolver={{ traefik_ssl_cert_resolver | default('dns') }}
+{% endif %}
 {% else %}
       - traefik.http.routers.{{ collabora_service_name }}.entrypoints=web
 {% endif %}

roles/drawio/README.md

@@ -1,38 +1,60 @@
-Role Name
-=========
+# Drawio
 
-A brief description of the role goes here.
+Ansible role to deploy [draw.io](https://www.drawio.com/) (the
+self-hosted `jgraph/drawio` container) via Docker Compose behind
+Traefik, with optional authentik ForwardAuth gating.
 
-Requirements
-------------
+## Requirements
 
-Any pre-requisites that may not be covered by Ansible itself or the role should be mentioned here. For instance, if the role uses the EC2 module, it may be a good idea to mention in this section that the boto package is required.
+- Docker and Docker Compose installed on the target host
+- Ansible collection: `community.docker`
+- Traefik with a shared `drawio_traefik_network` (default `proxy`)
+- For ForwardAuth: a reachable authentik embedded outpost endpoint
 
-Role Variables
---------------
+## Role variables
 
-A description of the settable variables for this role should go here, including any variables that are in defaults/main.yml, vars/main.yml, and any variables that can/should be set via parameters to the role. Any variables that are read from other roles and/or the global scope (ie. hostvars, group vars, etc.) should be mentioned here as well.
+Full spec with types and defaults: `meta/argument_specs.yml`. The most
+common overrides:
 
-Dependencies
-------------
+### Service
 
-A list of other roles hosted on Galaxy should go here, plus any details in regards to parameters that may need to be set for other roles, or variables that are used from other roles.
+- `drawio_domain`: canonical hostname used in the traefik Host rule
+  (default `drawio.local.test`).
+- `drawio_extra_domains`: additional hostnames the same container
+  should answer on (e.g. an internal `*.int.*` FQDN so a DMZ proxy
+  can reach drawio via a backend hostname).
+- `drawio_image`, `drawio_port`, `drawio_use_ssl`.
 
-Example Playbook
-----------------
+### Authentik ForwardAuth
 
-Including an example of how to use your role (for instance, with variables passed in as parameters) is always nice for users too:
+- `drawio_authentik_forward_auth`: set to `true` to gate the editor
+  behind authentik.
+- `drawio_authentik_forward_auth_url`: full URL of the embedded
+  outpost ForwardAuth endpoint, e.g.
+  `https://auth.example.com/outpost.goauthentik.io/auth/traefik`.
 
-    - hosts: servers
-      roles:
-         - { role: username.rolename, x: 42 }
+When enabled, traefik redirects unauthenticated requests to authentik
+for login and forwards the resulting `X-Authentik-*` identity headers
+downstream.
 
-License
--------
+## Dependencies
 
-BSD
+- Traefik network (`drawio_traefik_network`, default `proxy`)
+- Optional: authentik with a Proxy/ForwardAuth provider for drawio
+  (see the `authentik` role's `authentik_proxy_apps`).
 
-Author Information
-------------------
+## Example playbook
 
-An optional section for the role authors to include contact information, or a website (HTML is not allowed).
+```yaml
+- hosts: app_servers
+  roles:
+    - role: digitalboard.core.drawio
+      vars:
+        drawio_domain: "drawio.example.com"
+        drawio_authentik_forward_auth: true
+        drawio_authentik_forward_auth_url: "https://auth.example.com/outpost.goauthentik.io/auth/traefik"
+```
+
+## License
+
+MIT-0

roles/drawio/defaults/main.yml

@@ -11,10 +11,21 @@ drawio_docker_compose_dir: "{{ docker_compose_base_dir }}/{{ drawio_service_name
 
 # Service configuration
 drawio_domain: "drawio.local.test"
+# Additional hostnames the same drawio container should answer on
+# (e.g. an internal *.int.* FQDN so a DMZ reverseproxy can reach
+# drawio via a backend hostname covered by the local traefik cert).
+drawio_extra_domains: []
 drawio_image: "jgraph/drawio:latest"
 drawio_port: 8080
 drawio_extra_hosts: []
 
 # Traefik configuration
 drawio_traefik_network: "proxy"
-drawio_use_ssl: true
+drawio_use_ssl: true
+
+# Optional Authentik ForwardAuth (set to true and provide the URL to gate
+# drawio behind an authentik proxy provider). Expects the authentik
+# embedded outpost to expose the /outpost.goauthentik.io/auth/traefik
+# endpoint on the configured URL (typically the public auth.* FQDN).
+drawio_authentik_forward_auth: false
+drawio_authentik_forward_auth_url: ""

roles/drawio/handlers/main.yml

@@ -5,4 +5,4 @@
 - name: restart drawio
   community.docker.docker_compose_v2:
     project_src: "{{ drawio_docker_compose_dir }}"
-    state: restarted
+    state: present

roles/drawio/meta/argument_specs.yml

@@ -0,0 +1,64 @@
+---
+argument_specs:
+  main:
+    short_description: Deploy draw.io diagram editor via Docker Compose behind Traefik.
+    description:
+      - Renders a Compose stack for jgraph/drawio with traefik labels, optional
+        TLS and optional authentik ForwardAuth gating.
+    options:
+      docker_compose_base_dir:
+        type: path
+        default: /etc/docker/compose
+      drawio_service_name:
+        type: str
+        default: drawio
+      drawio_docker_compose_dir:
+        type: path
+        description: Defaults to C({{ docker_compose_base_dir }}/{{ drawio_service_name }}).
+
+      drawio_domain:
+        type: str
+        default: drawio.local.test
+        description: Canonical hostname used in the traefik Host rule.
+      drawio_extra_domains:
+        type: list
+        elements: str
+        default: []
+        description:
+          - Additional hostnames the same drawio container should answer on,
+            e.g. an internal C(*.int.*) FQDN so a DMZ reverse-proxy can reach
+            drawio via a backend hostname covered by the local traefik cert.
+      drawio_image:
+        type: str
+        default: jgraph/drawio:latest
+      drawio_port:
+        type: int
+        default: 8080
+      drawio_extra_hosts:
+        type: list
+        elements: str
+        default: []
+        description: C(extra_hosts) entries injected into the container (Docker C(host:ip) syntax).
+
+      drawio_traefik_network:
+        type: str
+        default: proxy
+      drawio_use_ssl:
+        type: bool
+        default: true
+
+      drawio_authentik_forward_auth:
+        type: bool
+        default: false
+        description:
+          - When true, traefik attaches a ForwardAuth middleware pointing at
+            the authentik embedded outpost. Unauthenticated requests are
+            redirected to authentik for login and the resulting
+            C(X-Authentik-*) identity headers are forwarded downstream.
+      drawio_authentik_forward_auth_url:
+        type: str
+        default: ''
+        description:
+          - URL of the authentik ForwardAuth endpoint, typically
+            C(https://auth.example.com/outpost.goauthentik.io/auth/traefik).
+            Required when C(drawio_authentik_forward_auth=true).

roles/drawio/templates/docker-compose.yml.j2

@@ -14,7 +14,7 @@ services:
     labels:
       - traefik.enable=true
       - traefik.docker.network={{ drawio_traefik_network }}
-      - traefik.http.routers.{{ drawio_service_name }}.rule=Host(`{{ drawio_domain }}`)
+      - traefik.http.routers.{{ drawio_service_name }}.rule={% set _all_domains = [drawio_domain] + (drawio_extra_domains | default([])) %}{% for d in _all_domains %}Host(`{{ d }}`){% if not loop.last %} || {% endif %}{% endfor +%}
       - traefik.http.services.{{ drawio_service_name }}.loadbalancer.server.port={{ drawio_port }}
 {% if drawio_use_ssl %}
       - traefik.http.routers.{{ drawio_service_name }}.entrypoints=websecure
@@ -22,6 +22,15 @@ services:
 {% else %}
       - traefik.http.routers.{{ drawio_service_name }}.entrypoints=web
 {% endif %}
+{% if drawio_authentik_forward_auth | default(false) %}
+      # ForwardAuth via the authentik embedded outpost. Unauthenticated
+      # requests get redirected to authentik to log in; authentik then
+      # sets X-Authentik-* headers traefik forwards downstream.
+      - traefik.http.middlewares.{{ drawio_service_name }}-authentik.forwardauth.address={{ drawio_authentik_forward_auth_url }}
+      - traefik.http.middlewares.{{ drawio_service_name }}-authentik.forwardauth.trustForwardHeader=true
+      - traefik.http.middlewares.{{ drawio_service_name }}-authentik.forwardauth.authResponseHeaders=X-authentik-username,X-authentik-groups,X-authentik-entitlements,X-authentik-email,X-authentik-name,X-authentik-uid,X-authentik-jwt,X-authentik-meta-jwks,X-authentik-meta-outpost,X-authentik-meta-provider,X-authentik-meta-app,X-authentik-meta-version
+      - traefik.http.routers.{{ drawio_service_name }}.middlewares={{ drawio_service_name }}-authentik
+{% endif %}
 
 networks:
   {{ drawio_traefik_network }}:

roles/garage/README.md

@@ -1,113 +1,116 @@
-Garage
-======
+# Garage
 
-Ansible role to deploy Garage S3-compatible object storage using Docker Compose.
+Ansible role to deploy [Garage](https://garagehq.deuxfleurs.fr/) S3-compatible
+object storage via Docker Compose, with declarative key/bucket
+provisioning and an optional WebUI behind htpasswd or authentik
+ForwardAuth.
 
-Requirements
-------------
+## Requirements
 
 - Docker and Docker Compose installed on the target host
 - Ansible collection: `community.docker`
-- Traefik reverse proxy (for external access)
+- `htpasswd` (from `apache2-utils` / `httpd-tools`) when the WebUI is
+  enabled and authentik ForwardAuth is *not* used
+- Traefik with a shared `garage_traefik_network` (default `proxy`)
 
-Role Variables
---------------
+## Role variables
 
-Key variables defined in `defaults/main.yml`:
+Full spec with types and defaults: `meta/argument_specs.yml`. The most
+common overrides:
 
-**Base Configuration:**
-- `docker_compose_base_dir`: Base directory for Docker Compose files (default: `/etc/docker/compose`)
-- `docker_volume_base_dir`: Base directory for Docker volumes (default: `/srv/data`)
+### Service
 
-**Garage Configuration:**
-- `garage_service_name`: Service name (default: `garage`)
-- `garage_image`: Garage Docker image (default: `dxflrs/garage:v2.1.0`)
-- `garage_s3_domain`: Domain for S3 API endpoint (default: `storage.local.test`)
-- `garage_web_domain`: Domain for S3 web endpoint (default: `web.storage.local.test`)
-- `garage_webui_domain`: Domain for web console (default: `console.storage.local.test`)
+- `garage_s3_domains`: FQDNs the S3 router accepts. First entry is the
+  canonical hostname and is used as `root_domain` in `garage.toml`.
+- `garage_web_domain`, `garage_webui_domain`: separate hostnames for
+  the S3-website endpoint and the console.
+- `garage_image`, `garage_replication_factor`, `garage_db_engine`,
+  `garage_s3_region`.
 
-**Garage Storage Configuration:**
-- `garage_replication_factor`: Replication factor (default: `1`)
-- `garage_compression_level`: Compression level (default: `1`)
-- `garage_db_engine`: Database engine (default: `lmdb`)
-- `garage_s3_region`: S3 region (default: `us-east-1`)
+### Required secrets
 
-**Garage Ports:**
-- `garage_s3_api_port`: S3 API port (default: `3900`)
-- `garage_s3_web_port`: S3 web port (default: `3902`)
-- `garage_admin_port`: Admin API port (default: `3903`)
-- `garage_rpc_port`: RPC port (default: `3901`)
+Generate with `openssl rand -hex 32` (32 bytes / 64 hex chars):
 
-**Garage Security:**
-- `garage_rpc_secret`: RPC secret for node communication
-- `garage_admin_token`: Admin API token
-- `garage_metrics_token`: Metrics API token
+- `garage_rpc_secret`: node-to-node RPC secret
+- `garage_admin_token`: admin API token
+- `garage_metrics_token`: metrics endpoint token
 
-**Garage WebUI Configuration:**
-- `garage_webui_enabled`: Enable web UI (default: `true`)
-- `garage_webui_image`: WebUI Docker image (default: `khairul169/garage-webui:latest`)
-- `garage_webui_port`: WebUI port (default: `3909`)
-- `garage_webui_username`: WebUI username (default: `admin`)
-- `garage_webui_password`: WebUI password in plaintext (default: `admin`)
+### WebUI authentication
 
-**Traefik Configuration:**
-- `garage_traefik_network`: Traefik network name (default: `proxy`)
-- `garage_internal_network`: Internal network name (default: `internal`)
-- `garage_use_ssl`: Enable SSL (default: `true`)
+Three modes:
 
-Dependencies
-------------
+1. **htpasswd** (default): `garage_webui_username` / `garage_webui_password`
+   in plaintext. The role hashes the password with
+   `htpasswd -nbBC 10`, persists the hash on disk, and re-verifies with
+   `htpasswd -vbB` so unchanged passwords don't churn the play.
+2. **authentik ForwardAuth**: set
+   `garage_webui_authentik_forward_auth: true` and
+   `garage_webui_authentik_forward_auth_url:
+   "https://auth.example.com/outpost.goauthentik.io/auth/traefik"`.
+   `AUTH_USER_PASS` is dropped from the container env so authentik is
+   the only gate.
+3. **Disabled**: `garage_webui_enabled: false`.
 
-This role requires:
-- Traefik reverse proxy to be configured and the `proxy` network to be created
-- `htpasswd` utility (from `apache2-utils` package) for generating bcrypt password hashes
+### Layout bootstrap
 
-Example Playbook
-----------------
+Setting `garage_bootstrap_enabled: true` runs the bootstrap task, which
+joins the local node to the layout (`zone: garage_bootstrap_zone`,
+capacity: `garage_bootstrap_capacity`) on the first run. The check
+tolerates the 16-char truncation that `garage layout show` performs.
+
+### Declarative S3 keys and buckets
+
+```yaml
+garage_s3_keys:
+  - name: nextcloud
+    buckets:
+      - name: nextcloud-data
+        permissions: [read, write]
+  - name: backup
+    buckets:
+      - name: restic-prod
+        permissions: [read, write, owner]
+```
+
+The role:
+
+- Lists existing keys (`garage key list`), creates missing ones
+- Lists existing buckets (`garage bucket list`), creates missing ones
+- Reads current permissions via `garage bucket info` and runs
+  `garage bucket allow` only when the current RWO flags for the key
+  don't already match the desired permissions
+
+`stdout` parsing is hardened against ANSI escapes and interleaved INFO
+log lines, so probe noise no longer produces spurious changes.
+
+## Dependencies
+
+- Traefik network (`garage_traefik_network`, default `proxy`)
+- Internal network (`garage_internal_network`, default `internal`)
+
+## Example playbook
 
 ```yaml
 - hosts: storage_servers
   roles:
-    - role: garage
+    - role: digitalboard.core.garage
       vars:
-        garage_s3_domain: "storage.example.com"
-        garage_rpc_secret: "your-secure-rpc-secret"
-        garage_admin_token: "your-admin-token"
-        garage_webui_enabled: true
-        garage_webui_username: "admin"
-        garage_webui_password: "secure-password"
+        garage_s3_domains:
+          - "storage.example.com"
+          - "storage.int.example.com"
+        garage_rpc_secret: "{{ vault_garage_rpc_secret }}"
+        garage_admin_token: "{{ vault_garage_admin_token }}"
+        garage_metrics_token: "{{ vault_garage_metrics_token }}"
+        garage_bootstrap_enabled: true
+        garage_webui_authentik_forward_auth: true
+        garage_webui_authentik_forward_auth_url: "https://auth.example.com/outpost.goauthentik.io/auth/traefik"
+        garage_s3_keys:
+          - name: nextcloud
+            buckets:
+              - name: nextcloud-data
+                permissions: [read, write]
 ```
 
-**Note:** The WebUI password is specified in plaintext and will be automatically hashed using bcrypt during deployment. The role uses `htpasswd` to generate a secure bcrypt hash that is then properly escaped for use in Docker Compose.
+## License
 
-Post-Installation
------------------
-
-After deployment, you need to configure the Garage cluster:
-
-1. Connect to the node and get the node ID:
-   ```bash
-   docker exec -ti garage /garage node id
-   ```
-
-2. Configure the node layout:
-   ```bash
-   docker exec -ti garage /garage layout assign -z dc1 -c 1G <node-id>
-   docker exec -ti garage /garage layout apply --version 1
-   ```
-
-3. Create a key for S3 access:
-   ```bash
-   docker exec -ti garage /garage key create my-key
-   ```
-
-4. Create a bucket:
-   ```bash
-   docker exec -ti garage /garage bucket create my-bucket
-   docker exec -ti garage /garage bucket allow my-bucket --read --write --key my-key
-   ```
-
-License
--------
-
-MIT-0
+MIT-0

roles/garage/defaults/main.yml

@@ -13,7 +13,11 @@ garage_docker_volume_dir: "{{ docker_volume_base_dir }}/{{ garage_service_name }
 
 # Garage service configuration
 garage_image: "dxflrs/garage:v2.1.0"
-garage_s3_domain: "storage.local.test"
+# FQDNs the garage S3 router accepts. The first entry is the canonical
+# domain and is also used as the virtual-hosted-style root_domain in
+# garage.toml; further entries cover internal *.int.* names.
+garage_s3_domains:
+  - "storage.local.test"
 garage_web_domain: "web.storage.local.test"
 garage_webui_domain: "console.storage.local.test"
 
@@ -21,10 +25,20 @@ garage_webui_domain: "console.storage.local.test"
 garage_webui_enabled: true
 garage_webui_image: "khairul169/garage-webui:latest"
 garage_webui_port: 3909
-# WebUI basic auth credentials (plaintext, will be hashed automatically)
+# WebUI basic auth credentials (plaintext, will be hashed automatically).
+# Ignored when garage_webui_authentik_forward_auth is true — in that case
+# authentik handles authentication via the ForwardAuth middleware below.
 garage_webui_username: "admin"
 garage_webui_password: "admin"
 
+# Optional Authentik ForwardAuth in front of the WebUI. When true:
+#   - the AUTH_USER_PASS env-var is dropped from the container so htpasswd
+#     isn't enforced; authentik is the only gate.
+#   - traefik attaches a ForwardAuth middleware pointing at the URL below.
+# Leave false to keep classic htpasswd protection.
+garage_webui_authentik_forward_auth: false
+garage_webui_authentik_forward_auth_url: ""
+
 # Garage ports
 garage_s3_api_port: 3900
 garage_s3_web_port: 3902

roles/garage/meta/argument_specs.yml

@@ -0,0 +1,169 @@
+---
+argument_specs:
+  main:
+    short_description: Deploy Garage S3-compatible object storage via Docker Compose.
+    description:
+      - Renders a Compose stack for Garage with traefik labels, configures the
+        node layout on first run, and (optionally) provisions S3 keys, buckets
+        and per-key permissions declaratively.
+      - The optional WebUI can be protected by classic htpasswd or by
+        authentik ForwardAuth.
+    options:
+      docker_compose_base_dir:
+        type: path
+        default: /etc/docker/compose
+      docker_volume_base_dir:
+        type: path
+        default: /srv/data
+      garage_service_name:
+        type: str
+        default: garage
+      garage_docker_compose_dir:
+        type: path
+        description: Defaults to C({{ docker_compose_base_dir }}/{{ garage_service_name }}).
+      garage_docker_volume_dir:
+        type: path
+        description: Defaults to C({{ docker_volume_base_dir }}/{{ garage_service_name }}).
+
+      garage_image:
+        type: str
+        default: dxflrs/garage:v2.1.0
+
+      garage_s3_domains:
+        type: list
+        elements: str
+        default: ['storage.local.test']
+        description:
+          - FQDNs the garage S3 router accepts. The first entry is the
+            canonical domain and is used as the virtual-hosted-style
+            C(root_domain) in C(garage.toml). Further entries cover internal
+            C(*.int.*) names.
+      garage_web_domain:
+        type: str
+        default: web.storage.local.test
+        description: Hostname serving the S3-website endpoint.
+      garage_webui_domain:
+        type: str
+        default: console.storage.local.test
+        description: Hostname serving the WebUI console.
+
+      garage_webui_enabled:
+        type: bool
+        default: true
+      garage_webui_image:
+        type: str
+        default: khairul169/garage-webui:latest
+      garage_webui_port:
+        type: int
+        default: 3909
+      garage_webui_username:
+        type: str
+        default: admin
+        description: htpasswd username. Ignored when C(garage_webui_authentik_forward_auth=true).
+      garage_webui_password:
+        type: str
+        default: admin
+        description:
+          - Plaintext password; hashed with C(htpasswd -nbBC 10) and persisted
+            on disk so re-runs don't churn. Ignored when authentik ForwardAuth
+            is enabled.
+      garage_webui_authentik_forward_auth:
+        type: bool
+        default: false
+        description:
+          - When true the C(AUTH_USER_PASS) env-var is dropped from the WebUI
+            container and traefik attaches a ForwardAuth middleware pointing
+            at the URL below. authentik is then the only gate; htpasswd is
+            disabled.
+      garage_webui_authentik_forward_auth_url:
+        type: str
+        default: ''
+        description:
+          - Required when C(garage_webui_authentik_forward_auth=true).
+            Typically C(https://auth.example.com/outpost.goauthentik.io/auth/traefik).
+
+      garage_s3_api_port:
+        type: int
+        default: 3900
+      garage_s3_web_port:
+        type: int
+        default: 3902
+      garage_admin_port:
+        type: int
+        default: 3903
+      garage_rpc_port:
+        type: int
+        default: 3901
+
+      garage_replication_factor:
+        type: int
+        default: 1
+      garage_compression_level:
+        type: int
+        default: 1
+      garage_db_engine:
+        type: str
+        choices: [lmdb, sqlite, sled]
+        default: lmdb
+      garage_s3_region:
+        type: str
+        default: us-east-1
+      garage_rpc_secret:
+        type: str
+        required: true
+        description: Hex secret for node-to-node RPC. Generate with C(openssl rand -hex 32).
+      garage_admin_token:
+        type: str
+        required: true
+      garage_metrics_token:
+        type: str
+        required: true
+
+      garage_traefik_network:
+        type: str
+        default: proxy
+      garage_internal_network:
+        type: str
+        default: internal
+      garage_use_ssl:
+        type: bool
+        default: true
+
+      garage_bootstrap_enabled:
+        type: bool
+        default: false
+        description: When true the bootstrap task ensures the node is in the layout.
+      garage_bootstrap_zone:
+        type: str
+        default: dc1
+        description: Zone label assigned during layout bootstrap.
+      garage_bootstrap_capacity:
+        type: str
+        default: 1G
+        description: Capacity string passed to C(garage layout assign -c).
+
+      garage_s3_keys:
+        type: list
+        elements: dict
+        default: []
+        description:
+          - Declarative key + bucket + permission provisioning. The role
+            creates missing keys, missing buckets, and runs C(bucket allow)
+            only when the current RWO flags for a given key don't match.
+        options:
+          name:
+            type: str
+            required: true
+          buckets:
+            type: list
+            elements: dict
+            description: Buckets this key gets access to.
+            options:
+              name:
+                type: str
+                required: true
+              permissions:
+                type: list
+                elements: str
+                choices: [read, write, owner]
+                required: true

roles/garage/tasks/bootstrap.yml

@@ -7,21 +7,27 @@
     container: "{{ garage_service_name }}"
     command: /garage node id -q
   register: _garage_node_id
+  changed_when: false
 
 - name: Extract short node ID
   ansible.builtin.set_fact:
     _garage_node_id_short: "{{ _garage_node_id.stdout.split('@')[0] }}"
 
+- name: Extract truncated node ID (first 16 chars, matches `garage layout show` output)
+  ansible.builtin.set_fact:
+    _garage_node_id_truncated: "{{ _garage_node_id_short[:16] }}"
+
 - name: Check if node layout is configured
   community.docker.docker_container_exec:
     container: "{{ garage_service_name }}"
     command: /garage layout show
   register: _garage_layout_show
   failed_when: false
+  changed_when: false
 
 - name: Check if node is in layout
   ansible.builtin.set_fact:
-    _node_in_layout: "{{ _garage_node_id_short in _garage_layout_show.stdout }}"
+    _node_in_layout: "{{ (_garage_node_id_truncated in _garage_layout_show.stdout) or (_garage_node_id_short in _garage_layout_show.stdout) }}"
 
 - name: Configure garage node layout
   community.docker.docker_container_exec:

roles/garage/tasks/main.yml

@@ -26,12 +26,77 @@
     dest: "{{ garage_docker_compose_dir }}/garage.toml"
     mode: '0644'
 
-- name: Generate bcrypt hash for webui password using htpasswd
-  ansible.builtin.shell: |
-    htpasswd -nbBC 10 "{{ garage_webui_username }}" "{{ garage_webui_password }}"
-  register: _garage_webui_password_hash
+- name: Set webui htpasswd activation fact
+  ansible.builtin.set_fact:
+    # htpasswd only runs when the WebUI is enabled AND authentik ForwardAuth
+    # is not handling authentication. When authentik is in front, the
+    # compose template drops AUTH_USER_PASS so no hash is needed.
+    _garage_webui_htpasswd_active: >-
+      {{
+        garage_webui_enabled
+        and not (garage_webui_authentik_forward_auth | default(false))
+      }}
+
+- name: Read cached webui htpasswd hash
+  ansible.builtin.slurp:
+    src: "{{ garage_docker_compose_dir }}/webui.htpasswd"
+  register: _garage_webui_htpasswd_cached
+  failed_when: false
   changed_when: false
-  when: garage_webui_enabled
+  when: _garage_webui_htpasswd_active
+
+- name: Verify cached webui htpasswd hash still matches password
+  ansible.builtin.command:
+    argv:
+      - htpasswd
+      - -vbB
+      - "{{ garage_docker_compose_dir }}/webui.htpasswd"
+      - "{{ garage_webui_username }}"
+      - "{{ garage_webui_password }}"
+  register: _garage_webui_htpasswd_verify
+  failed_when: false
+  changed_when: false
+  no_log: true
+  when:
+    - _garage_webui_htpasswd_active
+    - _garage_webui_htpasswd_cached.content is defined
+
+- name: Generate bcrypt hash for webui password using htpasswd
+  ansible.builtin.command:
+    argv:
+      - htpasswd
+      - -nbBC
+      - "10"
+      - "{{ garage_webui_username }}"
+      - "{{ garage_webui_password }}"
+  register: _garage_webui_password_hash_new
+  changed_when: true
+  when:
+    - _garage_webui_htpasswd_active
+    - (_garage_webui_htpasswd_cached.content is not defined)
+      or (_garage_webui_htpasswd_verify.rc | default(1) != 0)
+
+- name: Persist webui htpasswd hash on disk
+  ansible.builtin.copy:
+    content: "{{ _garage_webui_password_hash_new.stdout }}\n"
+    dest: "{{ garage_docker_compose_dir }}/webui.htpasswd"
+    mode: '0600'
+  when:
+    - _garage_webui_htpasswd_active
+    - _garage_webui_password_hash_new is changed
+
+- name: Load current webui htpasswd hash
+  ansible.builtin.slurp:
+    src: "{{ garage_docker_compose_dir }}/webui.htpasswd"
+  register: _garage_webui_htpasswd_current
+  changed_when: false
+  when: _garage_webui_htpasswd_active
+
+- name: Expose current webui htpasswd hash to template
+  ansible.builtin.set_fact:
+    _garage_webui_password_hash:
+      stdout: "{{ (_garage_webui_htpasswd_current.content | b64decode).strip() }}"
+  when: _garage_webui_htpasswd_active
 
 - name: Create docker-compose file for garage
   template:

roles/garage/tasks/provision.yml

@@ -4,11 +4,17 @@
     container: "{{ garage_service_name }}"
     command: /garage key list
   register: _existing_keys_output
+  changed_when: false
   when: garage_s3_keys | length > 0
 
 - name: Parse existing key names
   ansible.builtin.set_fact:
-    _existing_keys: "{{ _existing_keys_output.stdout_lines[1:] | select('match', '^GK') | map('regex_replace', '^\\S+\\s+\\S+\\s+(\\S+)\\s+.*$', '\\1') | list }}"
+    # `garage key list` columns: ID  Created  Name  Expiration.
+    # Data rows begin with a GK<hex> key ID; header is "ID  Created  ..."
+    # and INFO log lines may interleave on stderr (kept separate by
+    # docker_container_exec). Strip ANSI escapes defensively, filter to
+    # GK-prefixed rows, then take the 3rd whitespace-separated field.
+    _existing_keys: "{{ _existing_keys_output.stdout_lines | map('regex_replace', '\\x1b\\[[0-9;]*m', '') | select('match', '^GK[0-9a-fA-F]+') | map('regex_replace', '^\\S+\\s+\\S+\\s+(\\S+).*$', '\\1') | list }}"
   when: garage_s3_keys | length > 0
 
 - name: Create S3 keys
@@ -27,6 +33,7 @@
     command: /garage key info {{ item.name }}
   loop: "{{ garage_s3_keys }}"
   register: _key_info_results
+  changed_when: false
   when: garage_s3_keys | length > 0
 
 - name: Extract key IDs from info
@@ -42,11 +49,21 @@
     container: "{{ garage_service_name }}"
     command: /garage bucket list
   register: _existing_buckets_output
+  changed_when: false
   when: garage_s3_keys | length > 0
 
 - name: Parse existing bucket names
   ansible.builtin.set_fact:
-    _existing_buckets: "{{ _existing_buckets_output.stdout_lines[2:] | map('split') | map('first') | list }}"
+    # `garage bucket list` columns: ID  Created  Global aliases  Local aliases
+    # Data rows start with a hex bucket ID; filter to those and take the
+    # third whitespace-separated field (the global alias = bucket name).
+    _existing_buckets: >-
+      {{
+        _existing_buckets_output.stdout_lines
+        | select('match', '^[0-9a-f]{16}\\s')
+        | map('regex_replace', '^\\S+\\s+\\S+\\s+(\\S+).*$', '\\1')
+        | list
+      }}
   when: garage_s3_keys | length > 0
 
 - name: Get unique bucket names
@@ -64,12 +81,37 @@
     - item not in _existing_buckets
   failed_when: false
 
+- name: Get current bucket permissions
+  community.docker.docker_container_exec:
+    container: "{{ garage_service_name }}"
+    command: /garage bucket info {{ item.1.name }}
+  loop: "{{ garage_s3_keys | subelements('buckets', skip_missing=True) }}"
+  loop_control:
+    label: "{{ item.1.name }}"
+  register: _bucket_info_results
+  changed_when: false
+  when: garage_s3_keys | length > 0
+
 - name: Set bucket permissions using key IDs
   community.docker.docker_container_exec:
     container: "{{ garage_service_name }}"
-    command: /garage bucket allow {{ item.1.name }} {% for perm in item.1.permissions %}--{{ perm }} {% endfor %}--key {{ _key_id_map[item.0.name] }}
-  loop: "{{ garage_s3_keys | subelements('buckets', skip_missing=True) }}"
-  when: garage_s3_keys | length > 0
+    command: /garage bucket allow {{ item.item.1.name }} {% for perm in item.item.1.permissions %}--{{ perm }} {% endfor %}--key {{ _key_id_map[item.item.0.name] }}
+  loop: "{{ _bucket_info_results.results }}"
+  loop_control:
+    label: "{{ item.item.1.name }} -> {{ item.item.0.name }}"
+  when:
+    - garage_s3_keys | length > 0
+    - >-
+      (item.stdout | regex_search(
+        '(?m)^\s*' ~ _wanted_flags ~ '\s+' ~ _key_id_map[item.item.0.name]
+      )) is none
+  vars:
+    _wanted_flags: >-
+      {{
+        ('R' if 'read' in item.item.1.permissions else '-')
+        ~ ('W' if 'write' in item.item.1.permissions else '-')
+        ~ ('O' if 'owner' in item.item.1.permissions else '-')
+      }}
 
 # Export key credentials for use by other roles
 - name: Get detailed key information for all keys
@@ -78,6 +120,7 @@
     command: /garage key info {{ item.name }} --show-secret
   loop: "{{ garage_s3_keys }}"
   register: _key_details_results
+  changed_when: false
   when: garage_s3_keys | length > 0
 
 - name: Build garage S3 credentials map

roles/garage/templates/docker-compose.yml.j2

@@ -14,10 +14,13 @@ services:
       - traefik.enable=true
       - traefik.docker.network={{ garage_traefik_network }}
       # S3 API endpoint
-      - traefik.http.routers.{{ garage_service_name }}.rule=Host(`{{ garage_s3_domain }}`)
+      - traefik.http.routers.{{ garage_service_name }}.rule={% for d in garage_s3_domains %}Host(`{{ d }}`){% if not loop.last %} || {% endif %}{% endfor +%}
 {% if garage_use_ssl %}
       - traefik.http.routers.{{ garage_service_name }}.entrypoints=websecure
       - traefik.http.routers.{{ garage_service_name }}.tls=true
+{% if traefik_cert_mode | default('selfsigned') == 'acme' %}
+      - traefik.http.routers.{{ garage_service_name }}.tls.certresolver={{ traefik_ssl_cert_resolver | default('dns') }}
+{% endif %}
 {% else %}
       - traefik.http.routers.{{ garage_service_name }}.entrypoints=web
 {% endif %}
@@ -35,7 +38,9 @@ services:
     environment:
       API_BASE_URL: "http://{{ garage_service_name }}:{{ garage_admin_port }}"
       S3_ENDPOINT_URL: "http://{{ garage_service_name }}:{{ garage_s3_api_port }}"
+{% if not (garage_webui_authentik_forward_auth | default(false)) %}
       AUTH_USER_PASS: '{{ _garage_webui_password_hash.stdout | replace("$", "$$") }}'
+{% endif %}
     volumes:
       - {{ garage_docker_compose_dir }}/garage.toml:/etc/garage.toml:ro
     networks:
@@ -48,12 +53,25 @@ services:
 {% if garage_use_ssl %}
       - traefik.http.routers.{{ garage_service_name }}-console.entrypoints=websecure
       - traefik.http.routers.{{ garage_service_name }}-console.tls=true
+{% if traefik_cert_mode | default('selfsigned') == 'acme' %}
+      - traefik.http.routers.{{ garage_service_name }}-console.tls.certresolver={{ traefik_ssl_cert_resolver | default('dns') }}
+{% endif %}
 {% else %}
       - traefik.http.routers.{{ garage_service_name }}-console.entrypoints=web
 {% endif %}
       - traefik.http.routers.{{ garage_service_name }}-console.service={{ garage_service_name }}-console
       - traefik.http.routers.{{ garage_service_name }}-console.priority=10
       - traefik.http.services.{{ garage_service_name }}-console.loadbalancer.server.port={{ garage_webui_port }}
+{% if garage_webui_authentik_forward_auth | default(false) %}
+      # ForwardAuth via the authentik embedded outpost. Unauthenticated
+      # requests are redirected to authentik; authentik then forwards
+      # X-Authentik-* identity headers downstream. htpasswd is disabled
+      # in the env block above so authentik is the only gate.
+      - traefik.http.middlewares.{{ garage_service_name }}-console-authentik.forwardauth.address={{ garage_webui_authentik_forward_auth_url }}
+      - traefik.http.middlewares.{{ garage_service_name }}-console-authentik.forwardauth.trustForwardHeader=true
+      - traefik.http.middlewares.{{ garage_service_name }}-console-authentik.forwardauth.authResponseHeaders=X-authentik-username,X-authentik-groups,X-authentik-entitlements,X-authentik-email,X-authentik-name,X-authentik-uid,X-authentik-jwt,X-authentik-meta-jwks,X-authentik-meta-outpost,X-authentik-meta-provider,X-authentik-meta-app,X-authentik-meta-version
+      - traefik.http.routers.{{ garage_service_name }}-console.middlewares={{ garage_service_name }}-console-authentik
+{% endif %}
 {% endif %}
 
 networks:

roles/garage/templates/garage.toml.j2

@@ -14,7 +14,7 @@ rpc_secret = "{{ garage_rpc_secret }}"
 [s3_api]
 s3_region = "{{ garage_s3_region }}"
 api_bind_addr = "[::]:{{ garage_s3_api_port }}"
-root_domain = ".s3.{{ garage_s3_domain }}"
+root_domain = ".s3.{{ garage_s3_domains[0] }}"
 
 [s3_web]
 bind_addr = "[::]:{{ garage_s3_web_port }}"

roles/homarr/handlers/main.yml

@@ -5,4 +5,4 @@
 - name: restart homarr
   community.docker.docker_compose_v2:
     project_src: "{{ homarr_docker_compose_dir }}"
-    state: restarted
+    state: present

roles/nextcloud/README.md

@@ -0,0 +1,123 @@
+# Nextcloud
+
+Ansible role to deploy [Nextcloud](https://nextcloud.com/) (fpm) with
+Postgres and Redis via Docker Compose, optional Collabora WOPI
+integration, optional draw.io integration, optional notify_push
+companion, optional S3 primary storage, plus OIDC and LDAP user
+backends.
+
+## What this role does
+
+- Renders the Compose stack with traefik labels and TLS
+- Installs and enables a configurable list of Nextcloud apps idempotently
+- Configures Collabora (richdocuments), draw.io, OIDC providers and
+  LDAP via `occ` — every setting is read first and only written when
+  the stored value differs, so re-runs don't churn
+- Sets up notify_push (when enabled)
+- Applies an in-container PHP source workaround for the upstream
+  `UserConfig::getValueBool` TypeError on Nextcloud 33.0.3 (idempotent
+  via grep guard; remove the patch task once the deployed image
+  ships the upstream fix)
+
+## Requirements
+
+- Docker and Docker Compose installed on the target host
+- Ansible collection: `community.docker`
+- Traefik with a shared `nextcloud_traefik_network` (default `proxy`)
+
+## Role variables
+
+Full spec with types and defaults: `meta/argument_specs.yml`. The most
+common overrides:
+
+### Service
+
+- `nextcloud_domains`: FQDNs the router accepts. First entry is the
+  canonical hostname (used for `OVERWRITEHOST` and notify_push setup).
+  Further entries cover internal `*.int.*` names so Collabora's WOPI
+  callback hits the instance on a name with a valid cert.
+- `nextcloud_admin_password`, `nextcloud_postgres_password` (required).
+- `nextcloud_memory_limit_mb`, `nextcloud_upload_limit_mb`.
+
+### Collabora
+
+- `nextcloud_enable_collabora`: toggle integration with a separately
+  deployed Collabora server (see the `collabora` role).
+- `nextcloud_collabora_domain`: server-to-server hostname.
+- `nextcloud_collabora_public_domain` (optional): browser-facing
+  hostname when split-horizon uses different names.
+
+### Draw.io
+
+- `nextcloud_enable_drawio`: enable the `integration_drawio` app.
+- `nextcloud_drawio_url`: public draw.io URL.
+- `nextcloud_drawio_theme`, `nextcloud_drawio_offline`.
+
+### Notify push
+
+- `nextcloud_enable_notify_push`: deploy the notify_push companion.
+- `nextcloud_notify_push_domain` (optional): override the hostname
+  used by `occ notify_push:setup` to avoid hairpinning through the DMZ.
+
+### S3 primary storage
+
+Set `nextcloud_use_s3_storage: true` plus the `nextcloud_s3_*` block to
+point Nextcloud at an external S3-compatible store (e.g. Garage, MinIO).
+
+### OIDC
+
+`nextcloud_oidc_providers` is a list of OIDC providers registered with
+`user_oidc`. Required fields per entry: `identifier`, `display_name`,
+`client_id`, `client_secret`, `discovery_url`.
+
+### LDAP
+
+Set `nextcloud_ldap_enabled: true` and provide `nextcloud_ldap_config`
+as a dict of `occ ldap:set-config s01 KEY VALUE` pairs. The role reads
+the current LDAP config via `occ ldap:show-config s01 --output=json`
+and only calls `ldap:set-config` for keys whose stored value differs.
+
+## Dependencies
+
+- Traefik network (`nextcloud_traefik_network`, default `proxy`)
+- Optional: `collabora`, `drawio`, `garage` roles for the corresponding
+  integrations
+- Optional: an OIDC provider (Keycloak, authentik) reachable from
+  Nextcloud and a 389ds LDAP server when using `user_ldap`
+
+## Example playbook
+
+```yaml
+- hosts: app_servers
+  roles:
+    - role: digitalboard.core.nextcloud
+      vars:
+        nextcloud_domains:
+          - "cloud.example.com"
+          - "cloud.int.example.com"
+        nextcloud_admin_password: "{{ vault_nextcloud_admin_password }}"
+        nextcloud_postgres_password: "{{ vault_nextcloud_pg_password }}"
+
+        nextcloud_enable_collabora: true
+        nextcloud_collabora_domain: "office.int.example.com"
+        nextcloud_collabora_public_domain: "office.example.com"
+
+        nextcloud_enable_notify_push: true
+        nextcloud_notify_push_domain: "cloud.int.example.com"
+
+        nextcloud_oidc_providers:
+          - identifier: authentik
+            display_name: "Login with Authentik"
+            client_id: nextcloud
+            client_secret: "{{ vault_nextcloud_oidc_secret }}"
+            discovery_url: "https://auth.example.com/application/o/nextcloud/.well-known/openid-configuration"
+            mapping:
+              uid: preferred_username
+              display_name: name
+              email: email
+              groups: groups
+```
+
+## License
+
+MIT-0

roles/nextcloud/defaults/main.yml

@@ -9,7 +9,12 @@ nextcloud_service_name: nextcloud
 nextcloud_docker_compose_dir: "{{ docker_compose_base_dir }}/{{ nextcloud_service_name }}"
 nextcloud_docker_volume_dir: "{{ docker_volume_base_dir }}/{{ nextcloud_service_name }}"
 
-nextcloud_domain: "nextcloud.local.test"
+# FQDNs the nextcloud router accepts. The first entry is the canonical
+# domain (used for OVERWRITEHOST and the notify_push setup); further
+# entries cover internal *.int.* names so collabora's WOPI callback
+# hits us on a name with a valid cert.
+nextcloud_domains:
+  - "nextcloud.local.test"
 nextcloud_image: "nextcloud:fpm"
 nextcloud_redis_image: "redis:latest"
 nextcloud_port: 80
@@ -60,6 +65,12 @@ nextcloud_trusted_proxies: "172.16.0.0/12"
 # File locking and real-time push notifications
 nextcloud_enable_notify_push: false
 nextcloud_notify_push_image: "icewind1991/notify_push:1.3.1"
+# Domain used when calling `occ notify_push:setup`. Defaults to the
+# first nextcloud_domains entry (the canonical public name). Override
+# with an internal FQDN to avoid hairpinning the setup check through
+# the DMZ; the FQDN must also be in nextcloud_domains so the push
+# router matches it.
+# nextcloud_notify_push_domain: "cloud.int.example.com"
 
 # Non-default apps to install and enable
 nextcloud_apps_to_install:

roles/nextcloud/meta/argument_specs.yml

@@ -0,0 +1,253 @@
+---
+argument_specs:
+  main:
+    short_description: Deploy Nextcloud (fpm) + Redis + Postgres via Docker Compose.
+    description:
+      - Renders a Compose stack for Nextcloud with traefik labels, optional
+        Collabora WOPI integration, optional draw.io integration, optional
+        notify_push companion, optional S3 primary storage, OIDC providers
+        and LDAP user backend.
+      - "All C(occ)-driven configuration tasks are idempotent: each setting
+        is read with C(config:app:get) (or C(ldap:show-config)) first and
+        only written when the stored value differs."
+    options:
+      docker_compose_base_dir:
+        type: path
+        default: /etc/docker/compose
+      docker_volume_base_dir:
+        type: path
+        default: /srv/data
+      nextcloud_service_name:
+        type: str
+        default: nextcloud
+      nextcloud_docker_compose_dir:
+        type: path
+      nextcloud_docker_volume_dir:
+        type: path
+
+      nextcloud_domains:
+        type: list
+        elements: str
+        default: ['nextcloud.local.test']
+        description:
+          - FQDNs the nextcloud router accepts. The first entry is the
+            canonical domain (used for C(OVERWRITEHOST) and the
+            C(notify_push) setup). Further entries cover internal C(*.int.*)
+            names so Collabora's WOPI callback hits the instance on a name
+            with a valid certificate.
+      nextcloud_image:
+        type: str
+        default: nextcloud:fpm
+      nextcloud_redis_image:
+        type: str
+        default: redis:latest
+      nextcloud_port:
+        type: int
+        default: 80
+      nextcloud_extra_hosts:
+        type: list
+        elements: str
+        default: []
+      nextcloud_extra_networks:
+        type: list
+        elements: str
+        default: []
+      nextcloud_allow_local_remote_servers:
+        type: bool
+        default: false
+        description: Allow requests to local network from Nextcloud (dev only).
+
+      nextcloud_postgres_image:
+        type: str
+        default: postgres:15
+      nextcloud_postgres_db:
+        type: str
+        default: nextcloud
+      nextcloud_postgres_user:
+        type: str
+        default: nextcloud
+      nextcloud_postgres_password:
+        type: str
+        required: true
+
+      nextcloud_backend_network:
+        type: str
+        default: nextcloud-internal
+      nextcloud_traefik_network:
+        type: str
+        default: proxy
+      nextcloud_use_ssl:
+        type: bool
+        default: true
+
+      nextcloud_enable_collabora:
+        type: bool
+        default: true
+      nextcloud_collabora_domain:
+        type: str
+        default: office.local.test
+        description: Hostname Nextcloud uses to talk to Collabora server-to-server.
+      nextcloud_collabora_public_domain:
+        type: str
+        description:
+          - Optional browser-facing hostname for Collabora; defaults to
+            C(nextcloud_collabora_domain) when unset. Set when split-horizon
+            uses different names for browser and server traffic.
+      nextcloud_collabora_disable_cert_verification:
+        type: bool
+        default: false
+
+      nextcloud_enable_drawio:
+        type: bool
+        default: false
+        description: Enable the integration_drawio Nextcloud app and configure the URL/theme.
+      nextcloud_drawio_url:
+        type: str
+        default: ''
+        description: Public draw.io URL used by the integration_drawio app.
+      nextcloud_drawio_theme:
+        type: str
+        choices: [kennedy, atlas, dark, sketch, min]
+        default: kennedy
+      nextcloud_drawio_offline:
+        type: str
+        choices: ['yes', 'no']
+        default: 'yes'
+
+      nextcloud_use_s3_storage:
+        type: bool
+        default: false
+        description: Use S3 primary object storage instead of the local data dir.
+      nextcloud_s3_key:
+        type: str
+        default: changeme
+      nextcloud_s3_secret:
+        type: str
+        default: changeme
+      nextcloud_s3_region:
+        type: str
+        default: us-east-1
+      nextcloud_s3_bucket:
+        type: str
+        default: nextcloud
+      nextcloud_s3_host:
+        type: str
+        default: s3.example.com
+      nextcloud_s3_port:
+        type: int
+        default: 443
+      nextcloud_s3_ssl:
+        type: bool
+        default: true
+      nextcloud_s3_usepath_style:
+        type: bool
+        default: true
+      nextcloud_s3_autocreate:
+        type: bool
+        default: false
+
+      nextcloud_admin_user:
+        type: str
+        default: admin
+      nextcloud_admin_password:
+        type: str
+        required: true
+      nextcloud_memory_limit_mb:
+        type: int
+        default: 1024
+      nextcloud_upload_limit_mb:
+        type: int
+        default: 2048
+      nextcloud_scale_factor:
+        type: int
+        default: 2
+
+      nextcloud_trusted_proxies:
+        type: str
+        default: '172.16.0.0/12'
+        description: Trusted proxy CIDR(s) — by default the Docker internal range.
+
+      nextcloud_enable_notify_push:
+        type: bool
+        default: false
+      nextcloud_notify_push_image:
+        type: str
+        default: icewind1991/notify_push:1.3.1
+      nextcloud_notify_push_domain:
+        type: str
+        description:
+          - Hostname used when calling C(occ notify_push:setup). Defaults to
+            the first C(nextcloud_domains) entry. Override with an internal
+            FQDN to avoid hairpinning the setup check through the DMZ; the
+            FQDN must also be in C(nextcloud_domains).
+
+      nextcloud_apps_to_install:
+        type: list
+        elements: str
+        default:
+          - groupfolders
+          - richdocuments
+          - spreed
+          - user_ldap
+          - user_oidc
+          - whiteboard
+          - files_lock
+          - notify_push
+        description:
+          - Non-default Nextcloud apps to install + enable.
+            Install/enable detection is idempotent — re-runs report C(ok)
+            when the app is already present and enabled.
+
+      nextcloud_oidc_allow_selfsigned:
+        type: bool
+        default: false
+      nextcloud_oidc_providers:
+        type: list
+        elements: dict
+        default: []
+        description: OIDC providers registered with the user_oidc app.
+        options:
+          identifier:
+            type: str
+            required: true
+          display_name:
+            type: str
+            required: true
+          client_id:
+            type: str
+            required: true
+          client_secret:
+            type: str
+            required: true
+          discovery_url:
+            type: str
+            required: true
+          scope:
+            type: str
+            default: openid email profile
+          unique_uid:
+            type: bool
+            default: true
+          check_bearer:
+            type: bool
+            default: false
+          send_id_token_hint:
+            type: bool
+            default: true
+          mapping:
+            type: dict
+      nextcloud_oidc_providers_removed:
+        type: list
+        elements: str
+        default: []
+
+      nextcloud_ldap_enabled:
+        type: bool
+        default: false
+      nextcloud_ldap_config:
+        type: dict
+        default: {}
+        description:
+          - Key/value pairs passed to C(occ ldap:set-config s01 KEY VALUE).
+            The role reads the current config first and only invokes
+            C(set-config) when a stored value differs.

roles/nextcloud/tasks/collabora.yml

@@ -1,22 +1,55 @@
 #SPDX-License-Identifier: MIT-0
 ---
 # tasks file for configuring Collabora in Nextcloud
-- name: Configure Collabora WOPI URL
+- name: Read current richdocuments config values
+  community.docker.docker_container_exec:
+    container: "{{ nextcloud_docker_compose_dir | basename }}-nextcloud-1"
+    command: php /var/www/html/occ config:app:get richdocuments {{ item }}
+  loop:
+    - wopi_url
+    - public_wopi_url
+    - disable_certificate_verification
+    - wopi_allowlist
+  register: _richdocuments_current
+  changed_when: false
+  failed_when: false
+
+- name: Build map of current richdocuments config
+  ansible.builtin.set_fact:
+    _richdocuments_cfg: "{{ _richdocuments_cfg | default({}) | combine({item.item: (item.stdout | default('')).strip()}) }}"
+  loop: "{{ _richdocuments_current.results }}"
+  loop_control:
+    label: "{{ item.item }}"
+
+- name: Configure Collabora WOPI URL (server-to-server)
   community.docker.docker_container_exec:
     container: "{{ nextcloud_docker_compose_dir | basename }}-nextcloud-1"
     command: php /var/www/html/occ config:app:set richdocuments wopi_url --value=https://{{ nextcloud_collabora_domain }}
+  when: _richdocuments_cfg.wopi_url != ('https://' ~ nextcloud_collabora_domain)
+
+- name: Configure Collabora public WOPI URL (browser-facing)
+  community.docker.docker_container_exec:
+    container: "{{ nextcloud_docker_compose_dir | basename }}-nextcloud-1"
+    command: php /var/www/html/occ config:app:set richdocuments public_wopi_url --value=https://{{ nextcloud_collabora_public_domain }}
+  when:
+    - nextcloud_collabora_public_domain is defined
+    - nextcloud_collabora_public_domain != nextcloud_collabora_domain
+    - _richdocuments_cfg.public_wopi_url != ('https://' ~ nextcloud_collabora_public_domain)
 
 - name: Configure certificate verification for Collabora
   community.docker.docker_container_exec:
     container: "{{ nextcloud_docker_compose_dir | basename }}-nextcloud-1"
     command: php /var/www/html/occ config:app:set richdocuments disable_certificate_verification --value={{ nextcloud_collabora_disable_cert_verification | ternary('yes', 'no') }}
+  when: _richdocuments_cfg.disable_certificate_verification != (nextcloud_collabora_disable_cert_verification | ternary('yes', 'no'))
 
 - name: Set Collabora WOPI allowlist
   community.docker.docker_container_exec:
     container: "{{ nextcloud_docker_compose_dir | basename }}-nextcloud-1"
     command: php /var/www/html/occ config:app:set richdocuments wopi_allowlist --value=''
+  when: _richdocuments_cfg.wopi_allowlist | default('') != ''
 
 - name: Activate richdocuments configuration (fetch discovery from Collabora)
   community.docker.docker_container_exec:
     container: "{{ nextcloud_docker_compose_dir | basename }}-nextcloud-1"
-    command: php /var/www/html/occ richdocuments:activate-config
+    command: php /var/www/html/occ richdocuments:activate-config
+  changed_when: false

roles/nextcloud/tasks/drawio.yml

@@ -2,18 +2,41 @@
 ---
 # tasks file for configuring draw.io in Nextcloud
 
+- name: Read current drawio config values
+  community.docker.docker_container_exec:
+    container: "{{ nextcloud_docker_compose_dir | basename }}-nextcloud-1"
+    command: php /var/www/html/occ config:app:get drawio {{ item }}
+  loop:
+    - DrawioUrl
+    - DrawioTheme
+    - DrawioOffline
+  register: _drawio_current
+  changed_when: false
+  failed_when: false
+
+- name: Build map of current drawio config
+  ansible.builtin.set_fact:
+    _drawio_cfg: "{{ _drawio_cfg | default({}) | combine({item.item: (item.stdout | default('')).strip()}) }}"
+  loop: "{{ _drawio_current.results }}"
+  loop_control:
+    label: "{{ item.item }}"
+
 - name: Configure draw.io URL
   community.docker.docker_container_exec:
     container: "{{ nextcloud_docker_compose_dir | basename }}-nextcloud-1"
     command: php /var/www/html/occ config:app:set drawio DrawioUrl --value={{ nextcloud_drawio_url }}
-  when: nextcloud_drawio_url | length > 0
+  when:
+    - nextcloud_drawio_url | length > 0
+    - _drawio_cfg.DrawioUrl != nextcloud_drawio_url
 
 - name: Configure draw.io theme
   community.docker.docker_container_exec:
     container: "{{ nextcloud_docker_compose_dir | basename }}-nextcloud-1"
     command: php /var/www/html/occ config:app:set drawio DrawioTheme --value={{ nextcloud_drawio_theme }}
+  when: _drawio_cfg.DrawioTheme != (nextcloud_drawio_theme | string)
 
 - name: Configure draw.io offline mode
   community.docker.docker_container_exec:
     container: "{{ nextcloud_docker_compose_dir | basename }}-nextcloud-1"
-    command: php /var/www/html/occ config:app:set drawio DrawioOffline --value={{ nextcloud_drawio_offline }}
+    command: php /var/www/html/occ config:app:set drawio DrawioOffline --value={{ nextcloud_drawio_offline }}
+  when: _drawio_cfg.DrawioOffline != (nextcloud_drawio_offline | string)

roles/nextcloud/tasks/ldap.yml

@@ -15,6 +15,24 @@
     command: php /var/www/html/occ ldap:create-empty-config
   when: "'s01' not in ldap_show_config.stdout"
 
+- name: Read current LDAP config for s01
+  community.docker.docker_container_exec:
+    container: "{{ nextcloud_service_name }}-nextcloud-1"
+    command: php /var/www/html/occ ldap:show-config s01 --output=json
+  register: _ldap_show_s01
+  changed_when: false
+  failed_when: false
+
+- name: Parse current LDAP config
+  ansible.builtin.set_fact:
+    _ldap_current: >-
+      {{
+        (_ldap_show_s01.stdout | from_json) if (
+          (_ldap_show_s01.stdout | default('') | trim) is match('^[\\[{]')
+        ) else {}
+      }}
+  when: _ldap_show_s01.rc | default(1) == 0
+
 - name: Configure LDAP settings
   community.docker.docker_container_exec:
     container: "{{ nextcloud_service_name }}-nextcloud-1"
@@ -29,6 +47,7 @@
   loop_control:
     label: "{{ item.key }}"
   no_log: true
+  when: ((_ldap_current | default({})).get(item.key) | default(none) | string) != (item.value | string)
 
 - name: Test LDAP configuration
   community.docker.docker_container_exec:

roles/nextcloud/tasks/main.yml

@@ -49,6 +49,42 @@
     project_src: "{{ nextcloud_docker_compose_dir }}"
     state: present
 
+# nextcloud/server#59629: UserConfig::getValueBool() passes a non-string from
+# getTypedValue() into strtolower() under PHP 8.x + OPcache, throwing a
+# TypeError on every authenticated request once user_ldap is involved. Fix
+# is in master (PR #59646) but no stable33 backport landed before 33.0.4.
+# Apply the (string) cast in-container; idempotent via grep guard. Remove
+# this block once nextcloud_image >= 33.0.4.
+- name: Discover nextcloud php containers needing the UserConfig patch
+  ansible.builtin.shell:
+    cmd: >-
+      docker ps --filter "label=com.docker.compose.project={{ nextcloud_docker_compose_dir | basename }}"
+      --filter "label=com.docker.compose.service=nextcloud"
+      --format '{% raw %}{{.Names}}{% endraw %}'
+  register: _nextcloud_php_containers
+  changed_when: false
+
+- name: Check UserConfig.php patch status per container
+  ansible.builtin.shell:
+    cmd: >-
+      docker exec {{ item }} grep -q "strtolower((string)" /var/www/html/lib/private/Config/UserConfig.php
+  loop: "{{ _nextcloud_php_containers.stdout_lines }}"
+  register: _nextcloud_userconfig_check
+  changed_when: false
+  failed_when: false
+
+- name: Apply UserConfig::getValueBool string-cast workaround
+  ansible.builtin.shell:
+    cmd: >-
+      docker exec {{ item.item }}
+      sed -i 's|$b = strtolower($this->getTypedValue|$b = strtolower((string)$this->getTypedValue|'
+      /var/www/html/lib/private/Config/UserConfig.php
+  loop: "{{ _nextcloud_userconfig_check.results }}"
+  loop_control:
+    label: "{{ item.item }}"
+  when:
+    - item.rc | default(1) != 0
+
 - name: Wait for Nextcloud to be ready
   ansible.builtin.shell:
     cmd: docker compose exec -T nextcloud php /var/www/html/occ status --output=json

roles/nextcloud/tasks/notify_push.yml

@@ -2,7 +2,16 @@
 ---
 # tasks file for configuring notify_push in Nextcloud
 
+- name: Read current notify_push base endpoint
+  community.docker.docker_container_exec:
+    container: "{{ nextcloud_docker_compose_dir | basename }}-nextcloud-1"
+    command: php /var/www/html/occ config:app:get notify_push base_endpoint
+  register: _notify_push_current
+  changed_when: false
+  failed_when: false
+
 - name: Configure notify_push base endpoint
   community.docker.docker_container_exec:
     container: "{{ nextcloud_docker_compose_dir | basename }}-nextcloud-1"
-    command: php /var/www/html/occ notify_push:setup https://{{ nextcloud_domain }}/push
+    command: php /var/www/html/occ notify_push:setup https://{{ nextcloud_notify_push_domain | default(nextcloud_domains[0]) }}/push
+  when: (_notify_push_current.stdout | default('') | trim) != ('https://' ~ (nextcloud_notify_push_domain | default(nextcloud_domains[0])) ~ '/push')

roles/nextcloud/tasks/plugins.yml

@@ -8,7 +8,9 @@
     chdir: "{{ nextcloud_docker_compose_dir }}"
   loop: "{{ nextcloud_apps_to_install }}"
   register: app_install_result
-  changed_when: "'installed' in app_install_result.stdout"
+  changed_when:
+    - "'already installed' not in app_install_result.stdout"
+    - "'installed' in app_install_result.stdout"
   failed_when:
     - app_install_result.rc != 0
     - "'already installed' not in app_install_result.stdout"
@@ -19,7 +21,9 @@
     chdir: "{{ nextcloud_docker_compose_dir }}"
   loop: "{{ nextcloud_apps_to_install }}"
   register: app_enable_result
-  changed_when: "'enabled' in app_enable_result.stdout"
+  changed_when:
+    - "'already enabled' not in app_enable_result.stdout"
+    - "'enabled' in app_enable_result.stdout"
   failed_when:
     - app_enable_result.rc != 0
     - "'already enabled' not in app_enable_result.stdout"

roles/nextcloud/templates/docker-compose.yml.j2

@@ -35,10 +35,13 @@ services:
     labels:
       - traefik.enable=true
       - traefik.docker.network={{ nextcloud_traefik_network }}
-      - traefik.http.routers.{{ nextcloud_service_name }}.rule=Host(`{{ nextcloud_domain }}`)
+      - traefik.http.routers.{{ nextcloud_service_name }}.rule={% for d in nextcloud_domains %}Host(`{{ d }}`){% if not loop.last %} || {% endif %}{% endfor +%}
 {% if nextcloud_use_ssl %}
       - traefik.http.routers.{{ nextcloud_service_name }}.entrypoints=websecure
       - traefik.http.routers.{{ nextcloud_service_name }}.tls=true
+{% if traefik_cert_mode | default('selfsigned') == 'acme' %}
+      - traefik.http.routers.{{ nextcloud_service_name }}.tls.certresolver={{ traefik_ssl_cert_resolver | default('dns') }}
+{% endif %}
 {% else %}
       - traefik.http.routers.{{ nextcloud_service_name }}.entrypoints=web
 {% endif %}
@@ -60,7 +63,7 @@ services:
       PHP_MEMORY_LIMIT: {{ nextcloud_memory_limit_mb }}M
       PHP_UPLOAD_LIMIT: {{  nextcloud_upload_limit_mb }}M
       OVERWRITEPROTOCOL: https
-      OVERWRITEHOST: {{ nextcloud_domain }}
+      OVERWRITEHOST: {{ nextcloud_domains[0] }}
       TRUSTED_PROXIES: "{{ nextcloud_trusted_proxies }}"
     volumes:
       - {{ nextcloud_docker_volume_dir }}/nextcloud/:/var/www/html
@@ -69,6 +72,12 @@ services:
 {% for net in nextcloud_extra_networks %}
       - {{ net }}
 {% endfor %}
+{% if nextcloud_extra_hosts is defined and nextcloud_extra_hosts | length > 0 %}
+    extra_hosts:
+{% for host in nextcloud_extra_hosts %}
+      - "{{ host }}"
+{% endfor %}
+{% endif %}
 
   nextcloud:
     image: {{ nextcloud_image }}
@@ -88,7 +97,7 @@ services:
       PHP_MEMORY_LIMIT: {{ nextcloud_memory_limit_mb }}M
       PHP_UPLOAD_LIMIT: {{  nextcloud_upload_limit_mb }}M
       OVERWRITEPROTOCOL: https
-      OVERWRITEHOST: {{ nextcloud_domain }}
+      OVERWRITEHOST: {{ nextcloud_domains[0] }}
       TRUSTED_PROXIES: "{{ nextcloud_trusted_proxies }}"
 {% if nextcloud_use_s3_storage %}
       OBJECTSTORE_S3_KEY: {{ nextcloud_s3_key }}
@@ -127,7 +136,7 @@ services:
     environment:
       PORT: "7867"
       REDIS_URL: "redis://redis:6379"
-      DATABASE_URL: "postgres://{{ nextcloud_postgres_user }}:{{ nextcloud_postgres_password }}@db:5432/{{ nextcloud_postgres_db }}"
+      DATABASE_URL: "postgres://{{ nextcloud_postgres_user | urlencode | replace('/', '%2F') }}:{{ nextcloud_postgres_password | urlencode | replace('/', '%2F') }}@db:5432/{{ nextcloud_postgres_db }}"
       DATABASE_PREFIX: "oc_"
       NEXTCLOUD_URL: "http://nginx"
     networks:
@@ -136,11 +145,14 @@ services:
     labels:
       - traefik.enable=true
       - traefik.docker.network={{ nextcloud_traefik_network }}
-      - traefik.http.routers.{{ nextcloud_service_name }}-push.rule=Host(`{{ nextcloud_domain }}`) && PathPrefix(`/push`)
+      - traefik.http.routers.{{ nextcloud_service_name }}-push.rule=({% for d in nextcloud_domains %}Host(`{{ d }}`){% if not loop.last %} || {% endif %}{% endfor %}) && PathPrefix(`/push`)
       - traefik.http.services.{{ nextcloud_service_name }}-push.loadbalancer.server.port=7867
 {% if nextcloud_use_ssl %}
       - traefik.http.routers.{{ nextcloud_service_name }}-push.entrypoints=websecure
       - traefik.http.routers.{{ nextcloud_service_name }}-push.tls=true
+{% if traefik_cert_mode | default('selfsigned') == 'acme' %}
+      - traefik.http.routers.{{ nextcloud_service_name }}-push.tls.certresolver={{ traefik_ssl_cert_resolver | default('dns') }}
+{% endif %}
 {% else %}
       - traefik.http.routers.{{ nextcloud_service_name }}-push.entrypoints=web
 {% endif %}

roles/opencloud/handlers/main.yml

@@ -5,4 +5,4 @@
 - name: restart opencloud
   community.docker.docker_compose_v2:
     project_src: "{{ opencloud_docker_compose_dir }}"
-    state: restarted
+    state: present

roles/traefik/README.md

@@ -1,38 +1,98 @@
-Role Name
-=========
+# Traefik
 
-A brief description of the role goes here.
+Ansible role to deploy Traefik v3 as a reverse proxy via Docker Compose,
+either as a public-facing DMZ proxy (file provider) or as a backend
+application proxy (docker provider).
 
-Requirements
-------------
+## Requirements
 
-Any pre-requisites that may not be covered by Ansible itself or the role should be mentioned here. For instance, if the role uses the EC2 module, it may be a good idea to mention in this section that the boto package is required.
+- Docker and Docker Compose installed on the target host
+- Ansible collection: `community.docker`
+- For ACME DNS-01: an RFC2136-capable nameserver with a delegated zone
+  for `_acme-challenge` records and a TSIG key
 
-Role Variables
---------------
+## Role variables
 
-A description of the settable variables for this role should go here, including any variables that are in defaults/main.yml, vars/main.yml, and any variables that can/should be set via parameters to the role. Any variables that are read from other roles and/or the global scope (ie. hostvars, group vars, etc.) should be mentioned here as well.
+Full list with types and defaults: `meta/argument_specs.yml`. The most
+common overrides:
 
-Dependencies
-------------
+### Deployment mode
 
-A list of other roles hosted on Galaxy should go here, plus any details in regards to parameters that may need to be set for other roles, or variables that are used from other roles.
+- `traefik_mode`: `dmz` (file provider, routes to external backends) or
+  `backend` (docker provider, discovers local containers). Default `backend`.
+- `traefik_backend_servers_to_proxy`: in `dmz` mode, restrict which
+  inventory hosts the DMZ aggregates services from. Empty = all members
+  of `backend_servers`.
 
-Example Playbook
-----------------
+### Networking
 
-Including an example of how to use your role (for instance, with variables passed in as parameters) is always nice for users too:
+- `traefik_network`: docker network connecting traefik to its containers
+  (default `proxy`).
+- `traefik_extra_hosts`: list of `host:ip` entries injected as the
+  container's `extra_hosts`. Use when a downstream middleware
+  (e.g. ForwardAuth to authentik on a sibling LAN) must resolve a public
+  FQDN to an internal IP because the DMZ does not hairpin the public
+  address back inside.
 
-    - hosts: servers
-      roles:
-         - { role: username.rolename, x: 42 }
+### Certificates
 
-License
--------
+- `traefik_cert_mode`: `acme` (Let's Encrypt via DNS-01) or `selfsigned`
+  (local wildcard). Default `selfsigned`.
+- `traefik_acme_dns_zone`, `traefik_acme_dns_nameserver`,
+  `traefik_acme_tsig_key`, `traefik_acme_tsig_secret`: RFC2136 / TSIG
+  configuration for the ACME DNS-01 challenge.
+- `traefik_acme_tcp_only`: force lego's DNS lookups onto TCP/53 when the
+  container cannot reach the nameserver over UDP.
+- `traefik_acme_disable_ans_checks`: skip the authoritative-NS
+  propagation check when the SOA-listed NS resolves to an unreachable IP.
 
-BSD
+### Dashboard
 
-Author Information
-------------------
+- `traefik_enable_dashboard`: expose the traefik dashboard.
+- `traefik_dashboard_domain`: when set, publish the dashboard on this
+  Host rule instead of the insecure port.
 
-An optional section for the role authors to include contact information, or a website (HTML is not allowed).
+## Dependencies
+
+- Traefik network (`traefik_network`, default `proxy`) must be created
+  by the `base` role or by hand before this role runs.
+- In `dmz` mode, the proxied backend services advertise themselves via
+  the `traefik_services` host_var on each backend host.
+
+## Example playbook
+
+Backend mode (one app server per host, docker provider):
+
+```yaml
+- hosts: app_servers
+  roles:
+    - role: digitalboard.core.traefik
+      vars:
+        traefik_mode: backend
+        traefik_cert_mode: acme
+        traefik_ssl_email: ops@example.com
+        traefik_acme_dns_zone: "_acme.example.com."
+        traefik_acme_dns_nameserver: "10.0.0.53:53"
+        traefik_acme_tsig_key: "acme-key"
+        traefik_acme_tsig_secret: "{{ vault_traefik_tsig_secret }}"
+```
+
+DMZ mode (aggregates services from `backend_servers`):
+
+```yaml
+- hosts: dmz_servers
+  roles:
+    - role: digitalboard.core.traefik
+      vars:
+        traefik_mode: dmz
+        traefik_cert_mode: acme
+        traefik_backend_servers_to_proxy:
+          - app01
+          - app02
+        traefik_extra_hosts:
+          - "auth.example.com:172.16.19.101"
+```
+
+## License
+
+MIT-0

roles/traefik/defaults/main.yml

@@ -11,6 +11,13 @@ service_name: traefik
 docker_compose_dir: "{{ docker_compose_base_dir }}/{{ service_name }}"
 docker_volume_dir: "{{ docker_volume_base_dir }}/{{ service_name }}"
 
+# Optional /etc/hosts entries injected into the traefik container. Useful
+# when downstream middlewares (e.g. ForwardAuth to an authentik instance
+# running on a sibling LAN) need a public FQDN to resolve to an internal
+# IP because the DMZ doesn't hairpin the public address back inside.
+# Example: ["auth.example.com:172.16.19.101"]
+traefik_extra_hosts: []
+
 # Deployment mode: 'dmz' or 'backend'
 # - dmz: Public-facing reverse proxy that routes to backend servers using file provider
 # - backend: Application server with docker provider for local container discovery
@@ -33,6 +40,18 @@ traefik_acme_tsig_secret: ""  # TSIG secret
 traefik_acme_propagation_timeout: "120"
 traefik_acme_polling_interval: "2"
 traefik_acme_ttl: "60"
+# Force lego's DNS lookups (SOA resolution, propagation checks) onto
+# TCP instead of UDP. Useful when container egress can reach the
+# nameserver on TCP/53 but UDP/53 is blocked or unreliable. Sets the
+# upstream env var LEGO_EXPERIMENTAL_DNS_TCP_ONLY=true on the
+# traefik container.
+traefik_acme_tcp_only: false
+# Disable lego's propagation check against the zone's authoritative
+# nameservers. Use when the SOA-listed NS hostname resolves to an
+# address that isn't reachable from this traefik host (e.g. a DMZ
+# box that can only see the internal NS IP, not the public one).
+# lego still polls via the configured `resolvers:` list.
+traefik_acme_disable_ans_checks: false
 
 # Self-signed certificate configuration (for vagrant/testing)
 traefik_selfsigned_cert_dir: "{{ docker_volume_dir }}/certs"

roles/traefik/handlers/main.yml

@@ -5,4 +5,4 @@
 - name: restart traefik
   community.docker.docker_compose_v2:
     project_src: "{{ docker_compose_dir }}"
-    state: restarted
+    state: present

roles/traefik/meta/argument_specs.yml

@@ -0,0 +1,215 @@
+---
+argument_specs:
+  main:
+    short_description: Deploy Traefik v3 as DMZ or backend reverse proxy via Docker Compose.
+    description:
+      - Renders a Docker Compose stack for Traefik with either the file provider
+        (DMZ mode, routes to external backends) or the docker provider (backend
+        mode, discovers local containers via labels).
+      - Supports ACME DNS-01 issuance (RFC2136 / TSIG) or a self-signed cert
+        bundle for local/Vagrant setups.
+    options:
+      docker_compose_base_dir:
+        type: path
+        default: /etc/docker/compose
+        description: Base directory under which the per-service compose dir is created.
+      docker_volume_base_dir:
+        type: path
+        default: /srv/data
+        description: Base directory under which the per-service volume dir is created.
+      service_name:
+        type: str
+        default: traefik
+        description: Compose project / service name; also used to build the per-service paths.
+      docker_compose_dir:
+        type: path
+        description: Compose project directory; defaults to C({{ docker_compose_base_dir }}/{{ service_name }}).
+      docker_volume_dir:
+        type: path
+        description: Per-service volume directory; defaults to C({{ docker_volume_base_dir }}/{{ service_name }}).
+
+      traefik_extra_hosts:
+        type: list
+        elements: str
+        default: []
+        description:
+          - Entries injected as C(extra_hosts) on the traefik container.
+          - Each entry has the Docker syntax C("host:ip").
+          - Useful when a downstream middleware (e.g. ForwardAuth to authentik
+            on a sibling LAN) must resolve a public FQDN to an internal IP
+            because the DMZ does not hairpin the public address.
+
+      traefik_mode:
+        type: str
+        choices: [dmz, backend]
+        default: backend
+        description:
+          - C(dmz) configures the file provider so the proxy forwards to
+            backend hosts (typically aggregated from the C(backend_servers) group).
+          - C(backend) configures the docker provider for local container discovery.
+
+      traefik_use_ssl:
+        type: bool
+        default: true
+        description: Toggle TLS on the websecure entrypoint.
+      traefik_ssl_email:
+        type: str
+        default: admin@example.com
+        description: Contact e-mail used by the ACME resolver.
+      traefik_ssl_cert_resolver:
+        type: str
+        default: dns
+        description: Certificate resolver name referenced in router labels.
+      traefik_cert_mode:
+        type: str
+        choices: [acme, selfsigned]
+        default: selfsigned
+        description: C(acme) for Let's Encrypt via DNS-01, C(selfsigned) for a locally generated bundle.
+
+      traefik_acme_dns_zone:
+        type: str
+        default: ''
+        description: Delegated zone used for the TSIG-signed updates (e.g. C(_acme.example.com.)).
+      traefik_acme_dns_nameserver:
+        type: str
+        default: ''
+        description: Nameserver lego talks to for the DNS challenge (C(host:port)).
+      traefik_acme_tsig_algorithm:
+        type: str
+        default: hmac-sha256
+        description: TSIG algorithm.
+      traefik_acme_tsig_key:
+        type: str
+        default: ''
+        description: TSIG key name.
+      traefik_acme_tsig_secret:
+        type: str
+        default: ''
+        description: TSIG secret (base64).
+      traefik_acme_propagation_timeout:
+        type: str
+        default: '120'
+        description: lego DNS propagation timeout in seconds.
+      traefik_acme_polling_interval:
+        type: str
+        default: '2'
+        description: lego DNS propagation polling interval in seconds.
+      traefik_acme_ttl:
+        type: str
+        default: '60'
+        description: TTL applied to the C(_acme-challenge) TXT records.
+      traefik_acme_tcp_only:
+        type: bool
+        default: false
+        description:
+          - Sets C(LEGO_EXPERIMENTAL_DNS_TCP_ONLY=true) on the container so SOA
+            resolution and propagation checks use TCP/53. Use when UDP/53 is
+            blocked or unreliable on the container egress path.
+      traefik_acme_disable_ans_checks:
+        type: bool
+        default: false
+        description:
+          - Disable lego's propagation check against the zone's authoritative
+            nameservers (sets C(LEGO_DISABLE_CNAME_SUPPORT=) plus the
+            authoritative-NS-check skip). Use when the SOA-listed NS hostname
+            resolves to an address the proxy host cannot reach.
+
+      traefik_selfsigned_cert_dir:
+        type: path
+        description: Output directory for the self-signed bundle.
+      traefik_selfsigned_cert_days:
+        type: int
+        default: 365
+        description: Validity in days for the self-signed bundle.
+      traefik_selfsigned_common_name:
+        type: str
+        default: '*.local.test'
+        description: CN/SAN of the self-signed wildcard cert.
+
+      traefik_enable_dashboard:
+        type: bool
+        default: false
+        description: Expose the traefik dashboard.
+      traefik_dashboard_domain:
+        type: str
+        default: ''
+        description:
+          - When non-empty, the dashboard is published on this Host rule instead
+            of the insecure port 8080.
+
+      traefik_enable_access_logs:
+        type: bool
+        default: true
+      traefik_access_log_format:
+        type: str
+        choices: [common, json]
+        default: common
+      traefik_log_level:
+        type: str
+        choices: [DEBUG, INFO, WARN, ERROR, FATAL, PANIC]
+        default: INFO
+
+      traefik_network:
+        type: str
+        default: proxy
+        description: Docker network connecting traefik to its routable containers.
+
+      traefik_dmz_exposed_services:
+        type: list
+        elements: dict
+        default: []
+        description:
+          - In C(dmz) mode, services collected from backend host_vars are
+            published via the file provider. Each entry needs C(name),
+            C(domain), C(port); C(protocol) and C(backend_host) are optional.
+        options:
+          name:
+            type: str
+            required: true
+          domain:
+            type: str
+            required: true
+          port:
+            type: int
+            required: true
+          protocol:
+            type: str
+            choices: [http, https]
+            default: http
+          backend_host:
+            type: str
+            description: Override the auto-selected backend host.
+
+      traefik_services:
+        type: list
+        elements: dict
+        default: []
+        description:
+          - Services defined directly on the DMZ proxy (not auto-discovered
+            from a backend host). Each entry must set C(backend_host).
+        options:
+          name:
+            type: str
+            required: true
+          domain:
+            type: str
+            required: true
+          backend_host:
+            type: str
+            required: true
+          port:
+            type: int
+            required: true
+          protocol:
+            type: str
+            choices: [http, https]
+            default: http
+
+      traefik_backend_servers_to_proxy:
+        type: list
+        elements: str
+        default: []
+        description:
+          - In C(dmz) mode, explicit list of backend hosts the DMZ proxy
+            should aggregate exposed services from. Empty means all members
+            of the C(backend_servers) inventory group.

roles/traefik/tasks/main.yml

@@ -9,7 +9,18 @@
 
 - name: Build service registry from backend servers (DMZ mode)
   set_fact:
-    proxied_services: "{{ proxied_services | default([]) + hostvars[item].traefik_dmz_exposed_services | default([]) | map('combine', {'backend_host': hostvars[item].ansible_host | default(item)}) | list }}"
+    # Two-step merge so a service entry's own `backend_host` wins:
+    # entries that set it pass through unchanged, entries that don't
+    # get the backend host's ansible_host as fallback. The override
+    # lets a route target an internal FQDN covered by the backend
+    # cert's SANs instead of the raw IP (which would fail backend
+    # TLS verification at the proxy hop).
+    proxied_services: >-
+      {{
+        proxied_services | default([])
+        + (hostvars[item].traefik_dmz_exposed_services | default([]) | selectattr('backend_host', 'defined') | list)
+        + (hostvars[item].traefik_dmz_exposed_services | default([]) | rejectattr('backend_host', 'defined') | map('combine', {'backend_host': hostvars[item].ansible_host | default(item)}) | list)
+      }}
   loop: "{{ _backend_servers | default([]) }}"
   when: traefik_mode == 'dmz'
 

roles/traefik/templates/docker-compose.yml.j2

@@ -12,6 +12,9 @@ services:
       RFC2136_PROPAGATION_TIMEOUT: "{{ traefik_acme_propagation_timeout }}"
       RFC2136_POLLING_INTERVAL: "{{ traefik_acme_polling_interval }}"
       RFC2136_TTL: "{{ traefik_acme_ttl }}"
+{% if traefik_acme_tcp_only | default(false) %}
+      LEGO_EXPERIMENTAL_DNS_TCP_ONLY: "true"
+{% endif %}
 {% endif %}
     ports:
       - "80:80"
@@ -30,6 +33,12 @@ services:
 {% endif %}
     networks:
       - {{ traefik_network }}
+{% if traefik_extra_hosts | default([]) | length > 0 %}
+    extra_hosts:
+{%   for h in traefik_extra_hosts %}
+      - "{{ h }}"
+{%   endfor %}
+{% endif %}
 
 networks:
   {{ traefik_network }}:

roles/traefik/templates/traefik.yml.j2

@@ -48,6 +48,10 @@ certificatesResolvers:
         provider: rfc2136
         resolvers:
           - "{{ traefik_acme_dns_nameserver }}"
+{% if traefik_acme_disable_ans_checks | default(false) %}
+        propagation:
+          disableANSChecks: true
+{% endif %}
 {% endif %}
 
 {% if traefik_use_ssl %}