Skip to content

Traefik

Ingress and reverse proxy. The only service in the stack that publishes host ports; every other service, including the appliance VMs, is reached through Traefik on its own subdomain.
Runtime Container (Docker Swarm)
Tier Core
Node swarm-core
Image traefik:v3.7
URL N/A (is the ingress)
Auth N/A
Source ansible/stacks/core/traefik/

v3.3 was the original pin but has a bug that stops it discovering services on newer Docker daemons via the Swarm provider; bumped to v3.7 (fixed in issue #105/PR #106).

Ports

80 and 443, both published mode: host so Traefik sees the real client source IP rather than an overlay-network address.

Configuration

  • Two ACME cert resolvers: dns-cloudflare (DNS-01 via the Cloudflare API, the only method that can issue the *.lab.riversfamily.uk wildcard, used for internal-only services with no public A record) and http (HTTP-01, for zones not hosted on Cloudflare, e.g. client sites).
  • The dashboard is disabled (--api.dashboard=false) until it can be gated behind Authentik forward-auth.
  • A file provider (--providers.file.directory=/dynamic, watched) routes the non-Swarm appliance VMs (Pi-hole, Nextcloud, Home Assistant, UniFi), driven by the traefik_appliances list in group_vars/all/vars.yml. An appliance with an empty ip is skipped rather than routed to a bare port — see Home Assistant, currently unrouted for this reason.
  • traefik_trusted_proxies (group_vars/swarm_managers.yml, 10.0.0.0/8) and traefik_acme_email (homelab@riversfamily.email) are set once here and consumed by every other stack's compose template via | default(...).

Volumes

Volume Path Backing Contents
letsencrypt /letsencrypt Local ACME certificate storage
(bind) /var/run/docker.sock Host, read-only Swarm service discovery
(rendered) /dynamic Read-only File-provider config for the appliance VMs

Secrets

Vault variable Delivered as Purpose
vault_cloudflare_dns_api_token Swarm secret (cloudflare_dns_api_token), CF_DNS_API_TOKEN_FILE Cloudflare DNS-01 challenge

Gotchas

  • Traefik is the single point of ingress failure: if it is down, nothing in the stack is reachable, including the appliance VMs routed through its file provider.
  • The http resolver only matters if a non-Cloudflare zone (e.g. a client site) is ever fronted; every lab.riversfamily.uk service uses dns-cloudflare.