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

```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