Traefik

Traefik is the reverse proxy every other service sits behind — it terminates TLS and routes requests to the right container. Set it up first.

Verified 29 Jul 2026 against traefik:v3.6

Not exercised: recovering the proxy from a backup. The certificate store carries file permissions that a careless restore flattens, and nothing else is reachable until Traefik is back.

Installation

This path uses Cloudflare DNS-01 for a wildcard certificate — it doesn’t require port 80 to be publicly reachable. Needs: a domain with DNS at Cloudflare, and a Cloudflare API token (My Profile → API Tokens → Custom Token, with Zone:DNS:Edit + Zone:Zone:Read).

Don’t use Cloudflare, or don’t want a wildcard? See “Certificate strategy” under Going further — per-domain certificates work with or without Cloudflare.

1. From core/traefik/:

   cp .env.example .env

2. Set these in .env:

   ACME_EMAIL=you@example.com
   TRAEFIK_DASHBOARD_HOST=traefik.example.com
   CF_DNS_API_TOKEN=<your Cloudflare token>
   ACME_WILDCARD_DOMAIN=example.com

3. Render and start:

   bash ops/scripts/render.sh
   docker compose up -d

4. Confirm both containers are healthy:

   docker compose ps

Verify

curl -I https://<your-dashboard-domain>

The dashboard is Tailscale-only by default — connect over your tailnet to reach it.

Note

docker compose logs traefik shows nothing — this is expected. Traefik writes logs to files, not stdout:

docker exec traefik-core cat /var/log/traefik/traefik.log     # startup, ACME, errors
docker exec traefik-core cat /var/log/traefik/access.log      # every HTTP request

Check certificate issuance:

docker exec traefik-core cat /etc/traefik/acme/acme.json | jq '.[] | .Certificates[]?.domain // "no certs yet"'

Going further

Networking: IPv4-only or dual-stack?

The installation above is IPv4-only, which works for most setups. The failure dual-stack exists to prevent, in this architecture, is Tailscale: it always hands a client both addresses, and if the client connects over IPv6 while Traefik’s network is IPv4-only, Traefik loses the real client address and may wrongly refuse a Tailscale-only service.

That is the case this blueprint has hit, not the only one IPv6 matters for — another VPN that assigns IPv6, or a service reached directly over public IPv6 rather than through a proxy, raises the same question. Traffic arriving through a Cloudflare-proxied (orange-cloud) record is unaffected, because the real address is recovered from a trusted forwarded header instead of from the connection.

IPv4-only (default)

No extra setup. Skip this section if you don’t use Tailscale, or haven’t run into this.

Dual-stack

1. Generate your own IPv6 ULA prefix — never reuse a documentation example:

   RANDOM_HEX=$(openssl rand -hex 5)
   printf 'fd%s:%s:%s::/64\n' "${RANDOM_HEX:0:2}" "${RANDOM_HEX:2:4}" "${RANDOM_HEX:6:4}"

2. Check for subnet conflicts:

   docker network ls
   docker network inspect <network-name> --format '{{range .IPAM.Config}}{{.Subnet}} {{end}}'

3. Back up and edit /etc/docker/daemon.json, merging in:

   {
     "ipv6": true,
     "ip6tables": true,
     "userland-proxy": false
   }

   Then restart the daemon — this briefly affects every container on the host:

   sudo systemctl restart docker

4. In core/traefik/.env:

   PUBLIC_NETWORK_SUBNET_V4=172.30.0.0/16
   PUBLIC_NETWORK_SUBNET_V6=<your generated prefix>/64
   COMPOSE_FILE=docker-compose.yml:network-dual-stack.yml

Caution

Set COMPOSE_FILE as shown — don’t rely on remembering a -f network-dual-stack.yml flag. Once the dual-stack network exists, running docker compose without it makes Compose try to recreate the network as IPv4-only — which fails loudly if other containers are attached, or can silently revert it if not.

Full migration guide for adding this to an already-running deployment: core/traefik/docs/ipv6-dual-stack.md.

Certificate strategy

The path above is one of three. Two more work too — the only hard constraint is that wildcard certificates require DNS-01, since Let’s Encrypt doesn’t issue wildcards over HTTP-01 at all, regardless of this Blueprint.

Wildcard

One DNS-01 certificate covers *.example.com — what the installation above sets up. Needs a Cloudflare account and token; does not need port 80 reachable from the internet. Best when all your services live under one domain, and avoids registering every subdomain in public Certificate Transparency logs.

Per-domain (DNS-01)

Each application requests its own DNS-01 certificate through Cloudflare — still no public port 80 needed. Leave ACME_WILDCARD_DOMAIN unset; in each app’s .env set APP_TRAEFIK_CERT_RESOLVER=cloudflare-dns, and uncomment the tls.certresolver label in its docker-compose.yml.

Per-domain (HTTP-01)

Each application requests its own certificate via the standard HTTP-01 challenge — no Cloudflare account or token at all. Requires port 80 to be publicly reachable on this server. Leave ACME_WILDCARD_DOMAIN unset; in each app’s .env set APP_TRAEFIK_CERT_RESOLVER=httpResolver, and uncomment the tls.certresolver label.

These combine, too: keep a wildcard for your main domain and let individual apps opt into their own certificate (either resolver) via the same per-app label.

Cloudflare’s proxy status (orange-cloud vs. DNS-only) is a separate, per-record choice — independent of certificate strategy and resolver, and irrelevant to the HTTP-01 path above.

Troubleshooting

Caution

A 403 from a Tailscale client that should be allowed — check the access log’s ClientHost field. 100.x.x.x or fd7a:115c:a1e0::... is correct. 172.x.x.x from a remote client is the dual-stack issue above. 172.x.x.x from a curl run on the Traefik host itself is a different, harmless Docker behavior (hairpin NAT) — test from a separate client instead.

docker compose logs traefik 2>&1 | grep -iE "acme|cert|challenge" | tail -20

Most first-setup certificate failures are a Cloudflare token missing zone permissions, or a mismatch between ACME_WILDCARD_DOMAIN and the per-app tls.certresolver label state.

Tip

docker compose config prints every .env value, including CF_DNS_API_TOKEN. Redact before sharing it anywhere:

docker compose config | sed -E 's/(CF_DNS_API_TOKEN: ).*/\1***REDACTED***/'

Updates

# Read release notes first: https://github.com/traefik/traefik/releases
# Bump TRAEFIK_IMAGE in .env, then:
bash ops/scripts/render.sh
docker compose pull
docker compose up -d
docker compose logs traefik 2>&1 | grep -i error   # should be empty

Never jump major versions without reading the migration guide — the configuration schema changes.

Repository files

• core/traefik/README.md — full setup, security middleware system, CrowdSec plugin integration
• core/traefik/docs/ipv6-dual-stack.md — dual-stack networking in depth
• core/traefik/.env.example — all configurable variables
• docs/standards/traefik-security.md — access policies, security levels, TLS profiles
• TROUBLESHOOTING.md — symptoms this blueprint has hit, with their fixes
• docs/standards/troubleshooting.md — the layer-by-layer method and command reference