What’s in this file and what isn’t
traefik.yml is the static config: entry points, where routes come from, how to get certificates, logs, plugins.
Traefik reads it once, at startup, so any change means docker compose restart traefik and a few seconds when no
site opens.
Routers, middleware and services aren’t here — they’re dynamic config: container labels (Traefik labels) and
files in dynamic/ (at the end of this page). ${…} variables aren’t substituted in traefik.yml: Traefik reads
the file itself, not compose (traefik.yml doesn’t substitute variables).
The file, block by block
Domains are replaced with example.org and example.net; the Cloudflare network lists are shortened.
experimental:
plugins:
crowdsec-bouncer-traefik-plugin:
moduleName: "github.com/maxlerebourg/crowdsec-bouncer-traefik-plugin"
version: "v1.8.1"The CrowdSec bouncer plugin: the name on the left is what dynamic/crowdsec.yml uses to attach it (CrowdSec with Traefik behind Cloudflare). Traefik downloads the plugin from GitHub on every start, so pin the version with a tag.
default no plugins
global:
checkNewVersion: false
sendAnonymousUsage: falseNo new-version check: the image tag sets the version, and otherwise Traefik goes looking for updates and logs about them. Anonymous stats are off anyway — the line is for whoever reads the file.
default:checkNewVersion truesendAnonymousUsage false
api:
dashboard: false
debug: falseThe dashboard is a page with every router and its errors. It isn’t exposed by itself: it needs a router on api@internal with a password and the ban. Turn it on while debugging; api.insecure: true would open it on port 8080 with no protection.
default:dashboard trueinsecure false
log:
level: INFO
filePath: "/logs/traefik.log"INFO adds events: which certificates were obtained, which providers connected. DEBUG is for troubleshooting; the log grows fast. With filePath the log goes only to the file, and docker logs traefik is empty.
default:level ERRORfilePath stdout
maxSize: 10
maxBackups: 5
maxAge: 7
compress: trueBuilt-in rotation: a new file after 10 MB, 5 old ones kept, at most 7 days, old ones gzipped. Don’t add traefik.log to logrotate: two mechanisms on one file get in each other’s way (Traefik logs).
default:maxSize 100maxBackups 0 — allmaxAge 0 — no limitcompress false
accesslog:
addInternals: true
format: json
filePath: "/logs/access.log"The request log in JSON, one line per request: address, router, status code, duration. Log parsers such as CrowdSec or vector take their events from it (Traefik logs). A file rather than stdout because there can be several readers; logrotate rotates it with a USR1 signal.
default:format commonaddInternals false
entryPoints:
http:
address: ":80"
http:
aliasHeadersStrategy: delete
redirections:
entryPoint:
to: https
scheme: httpsEvery request on 80 goes to HTTPS. The redirect’s priority beats any router, so http routers and redirectscheme in service labels are no longer needed. The names http and https are arbitrary; labels refer to them. aliasHeadersStrategy — in the next block.
default:permanent truepriority MaxInt−1
https:
address: ":443"
http:
aliasHeadersStrategy: delete
tls:
certResolver: cloudflare
domains:
- main: "example.org"
sans:
- "*.example.org"
- main: "example.net"
sans:
- "*.example.net"Every router on this entry point gets TLS and a certificate from the cloudflare resolver. The wildcard is requested here, not on a router: the certificate doesn’t depend on any single service (Traefik and Let’s Encrypt). aliasHeadersStrategy: delete drops headers with _ or . in the name: PHP and nginx read X_Auth_User as X-Auth-User, so a visitor could forge a header that Traefik sets. reject instead of delete answers such a request with 400. Without the line, Traefik 3.7 logs a warning for each entry point.
default:aliasHeadersStrategy keep
forwardedHeaders:
trustedIPs:
# Cloudflare IPv4
- 173.245.48.0/20
- 103.21.244.0/22
# … 13 more IPv4 networks
# Cloudflare IPv6
- 2400:cb00::/32
# … 6 more IPv6 networksTraefik accepts X-Forwarded-* only from these addresses and overwrites it from anyone else — otherwise any visitor could pose as another address. Without this block, the log and CrowdSec show Cloudflare instead of visitors. The list: cloudflare.com/ips.
providers:
docker:
endpoint: "unix:///var/run/docker.sock"
exposedByDefault: false
watch: trueOnly containers with traefik.enable=true are exposed. With the default, every container with a port would go public under its own name. Routes are rebuilt on Docker events at most once every 2 s.
default:exposedByDefault truewatch true
file:
directory: /dynamic/
watch: trueA directory, not a single file: a single-file mount doesn’t see changes after git pull (Single-file mounts). Edits in dynamic/ apply without a restart.
certificatesResolvers:
cloudflare:
acme:
email: [email protected]
storage: acme.jsonThe Let’s Encrypt account email, written literally (traefik.yml doesn’t substitute variables). acme.json holds the account key and every certificate: mode 600, never in git, always in backups.
default:storage acme.json
caServer: https://acme-v02.api.letsencrypt.org/directory
# caServer: https://acme-staging-v02.api.letsencrypt.org/directoryThe production Let’s Encrypt server issues certificates browsers trust. The staging server is for experiments: higher limits, untrusted certificates; after switching back, clear acme.json.
default production server
dnsChallenge:
provider: cloudflare
resolvers:
- "1.1.1.1:53"
- "1.0.0.1:53"DNS-01: Traefik creates the TXT record itself through the Cloudflare API — the only way to get a wildcard. The token is CF_DNS_API_TOKEN_FILE from a Docker secret (Secrets in Docker stacks). Check the record at Cloudflare’s DNS: it sees the record before anyone else.
Not in the file, but often needed
entryPoints:
https:
transport:
respondingTimeouts:
readTimeout: 600sWithin readTimeout Traefik must read the whole request, body included. A large upload over a slow link breaks off at one minute — raise it on the entry point that takes uploads.
default:readTimeout 60swriteTimeout 0idleTimeout 180s
http3: {}HTTP/3 over QUIC. It also needs a UDP port: - 443:443/udp in compose. Works only for routers with TLS.
proxyProtocol:
trustedIPs: ["10.0.0.5"]PROXY protocol — when a TCP load balancer in front of Traefik passes the visitor’s address at the start of the connection. Only from the balancer’s addresses.
serversTransport:
insecureSkipVerify: trueDon’t verify certificates of services behind Traefik — for a service that serves HTTPS itself with a self-signed certificate. Here it applies to every service at once; for one service, use a serversTransport in dynamic config and have the service refer to it by name with the provider: serversTransport: insecure@file.
default false
ping: {}
metrics:
prometheus: {}/ping is for a compose healthcheck: traefik healthcheck --ping. Metrics — requests, status codes and timings per router, for Grafana. Both live on the traefik entry point (8080); don’t publish it.
providers:
docker:
network: proxyThe network Traefik uses to reach containers. On the server it’s set in every service with the traefik.docker.network label; one line here replaces them all.
default:network empty — Traefik picks
certificatesResolvers:
letsencrypt:
acme:
email: [email protected]
storage: acme.json
httpChallenge:
entryPoint: httpWithout a wildcard you don’t need DNS-01: HTTP-01 validates through port 80, tlsChallenge: {} through 443.
default:keyType RSA4096certificatesDuration 2160 h
dnsChallenge:
propagation:
delayBeforeChecks: 60sA pause before, or skipping, the TXT propagation check when Cloudflare answers slowly. Older configs use delayBeforeCheck and disablePropagationCheck: Traefik 3.7 still understands them but logs a deprecation warning.
default:delayBeforeChecks 0sdisableChecks false
Next door: what lives in dynamic/
Dynamic config is picked up without a restart. On the server data/dynamic/ holds three files: TLS options, rate
limits, and the ban middleware (crowdsec.yml, covered in CrowdSec with Traefik behind Cloudflare).
tls:
options:
default:
sniStrict: trueTraefik drops a connection with no site name or a foreign name instead of serving TRAEFIK DEFAULT CERT: a scanner hitting the server’s address won’t learn which sites live there.
default false
http:
middlewares:
global-ratelimit:
rateLimit:
average: 100
burst: 50
period: 1sOn average 100 requests per period from one address, plus a burst of up to 50. The limit is counted per address, not for the whole router.
default:average 0 — offburst 1period 1s
sourceCriterion:
ipStrategy:
depth: 1The visitor’s address is the first from the right in X-Forwarded-For: Cloudflare appended it. Without depth the limit would be counted by Cloudflare addresses and shared by everyone coming through one node.
If it doesn’t work
After editing traefik.yml the container restarts in a loop
- Cause
- An error in the static config — Traefik won’t start.
- Fix
docker logs traefik --tail 20shows the line; if you can’t find it fast,git checkout -- data/traefik.yml && docker compose restart traefik.
docker logs traefik is empty
- Cause
log.filePathis set — the log goes to a file.- Fix
tail -f /opt/traefik/data/logs/traefik.log.
The request log and CrowdSec show only Cloudflare addresses
- Cause
- No
forwardedHeaders.trustedIPson the entry point, or the list of Cloudflare networks is out of date. - Fix
- Compare the list with cloudflare.com/ips.
The rate limit hits everyone at once
- Cause
rateLimithas noipStrategy.depth: 1, so the limit is shared per Cloudflare node.- Fix
- Add
sourceCriterion.ipStrategy.depth: 1.
A new service is exposed though it has no traefik.enable
- Cause
exposedByDefaultisn’t set and stayedtrue.- Fix
- Set
exposedByDefault: falseand restart Traefik.
The wildcard isn’t issued; the log mentions TXT record propagation
- Cause
- Cloudflare hadn’t spread the record before the check.
- Fix
- Add
propagation.delayBeforeChecks: 60s; details — Traefik and Let’s Encrypt.
How to check
# the Traefik container's ports are 80 and 443
docker port traefik
# 80/tcp -> 0.0.0.0:80
# 443/tcp -> 0.0.0.0:443
# the certificate is a wildcard from Let's Encrypt
echo | openssl s_client -connect whoami.example.org:443 -servername whoami.example.org 2>/dev/null \
| openssl x509 -noout -subject -ext subjectAltName
# DNS:*.example.org, DNS:example.org
# without a site name the connection is dropped (sniStrict)
echo | openssl s_client -connect 203.0.113.10:443 2>&1 | grep -iE 'alert|error' | head -2
# behind Cloudflare, Traefik sees the visitor's address, not Cloudflare's
curl -s https://whoami.example.org | grep -i '^X-Real-Ip'