Simon Bärlocher 3236ca332f

docs(collection): document all roles and fix metadata drift

Replace ansible-galaxy init placeholders across the collection and
correct documentation that drifted from the code, after a multi-agent
review of every role README against its defaults, tasks and templates.

Collection level:
- README: role table for all 16 roles, requirements and role-ordering
- galaxy.yml: declare community.docker and community.general deps,
  real description/tags/urls; normalize license to MIT-0
- meta/runtime.yml: requires_ansible '>=2.15.0'
- plugins/README: document the homarr_layout filter and
  garage_credentials lookup instead of scaffold boilerplate

Per-role meta/main.yml and README for the placeholder roles
(389ds, authentik, authentik_outpost_ldap, base, collabora, drawio,
garage, homarr, httpbin, keycloak, nextcloud, opencloud, traefik).

Correctness fixes found during review:
- keycloak: wrong domain default, drop invented keycloak_cert_resolver,
  document the provisioning feature
- garage: root_domain is .s3.<first-entry>, not the bare domain
- opnform: jwt/front_api secrets use `openssl rand -hex 32`; align the
  validation fail_msg in tasks/main.yml accordingly
- send: S3 example references garage_s3_domains[0] (was singular)
- opencloud: document required opencloud_wopi_domain

License normalized to MIT-0 across galaxy.yml, role meta and READMEs to
match the SPDX headers.

2026-05-27 23:12:24 +02:00

3.4 KiB

Raw Blame History

Traefik

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

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

Full list with types and defaults: meta/argument_specs.yml. The most common overrides:

Deployment mode

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.

Networking

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.

Certificates

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.

Dashboard

traefik_enable_dashboard: expose the traefik dashboard.
traefik_dashboard_domain: when set, publish the dashboard on this Host rule instead of the insecure port.

Dependencies

Run digitalboard.core.base first (or otherwise install Docker and the community.docker collection); this role manages containers and networks through community.docker.
The Traefik network (traefik_network, default proxy) is created by this role (community.docker.docker_network, state present), so no pre-creation is required.
In dmz mode, backend hosts advertise the services to aggregate via the traefik_dmz_exposed_services host_var; traefik_services defines extra routes directly on the DMZ host (each entry must set backend_host).

Example playbook

Backend mode (one app server per host, docker provider):

- 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):

- 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

3.4 KiB Raw Blame History