traefik

Identity

• Docker image: traefik:v3 (current stable; traefik:latest tracks major version)
• Binary install: /usr/local/bin/traefik (when running outside Docker)
• Static config: /etc/traefik/traefik.yml (or traefik.toml; YAML preferred)
• Dynamic config dir: /etc/traefik/dynamic/ (watched by file provider)
• Docker socket: /var/run/docker.sock (mounted read-only into the Traefik container)
• Dashboard port: 8080/tcp (default; disable or protect in production)
• Logs: Docker: docker logs traefik; Systemd: journalctl -u traefik
• Distro install: apt install traefik / download binary from https://github.com/traefik/traefik/releases

Key Operations

Expected Ports

• 80/tcp — web entrypoint (HTTP)
• 443/tcp — websecure entrypoint (HTTPS)
• 8080/tcp — dashboard/API (disable or restrict in production)
• Verify: ss -tlnp | grep traefik or docker port traefik
• Firewall: sudo ufw allow 80,443/tcp (do NOT expose 8080 publicly without auth)

Health Checks

1. curl -sf http://localhost:8080/ping → OK
2. curl -sI http://localhost → HTTP response, not Connection refused
3. curl -s http://localhost:8080/api/http/routers | jq 'length' → count > 0
4. docker logs traefik 2>&1 | grep -i error | tail -20 → no unexpected errors

Common Failures

Pain Points

• Static vs dynamic config split: entrypoints, providers, certificatesResolvers, and log are static — they require a Traefik restart to change. Routers, services, and middlewares are dynamic — Traefik reloads them automatically. Confusing the two is the most common source of "my change did nothing" bugs.
• Entrypoints are static-only: You cannot define a new entrypoint via a Docker label or file provider. Add them to traefik.yml and restart.
• Docker labels are dynamic config: They are re-evaluated automatically as containers start/stop. No restart needed for label changes — but the container itself must restart.
• ACME requires persistent storage: acme.json must survive Traefik restarts. Use a named Docker volume or a bind-mounted path. Losing it forces re-issuance and may hit rate limits.
• Dashboard has no auth by default: With api.insecure: true, anyone who can reach port 8080 sees your full routing config. Always protect it with a middleware or bind to 127.0.0.1:8080 in production.
• Traefik v2 vs v3 differences: v3 removes the pilot section, changes some middleware names (e.g., ReplacePathRegex capitalization), and introduces the Hub integration. Docker Compose examples online are often v2 — check the image: tag before copying.
• exposedByDefault: false is the safe default: With true, every container gets a router — including databases and internal services. Set to false and opt in with traefik.enable=true.
• @provider suffix in cross-provider references: A middleware defined via Docker labels is name@docker. If a file-provider router references it, the full name name@docker is required.

References

See references/ for:

• traefik.yml.annotated — full static config with every directive explained, plus a dynamic config example
• common-patterns.md — Docker Compose setup, label-based routing, HTTPS, middlewares, TCP, load balancing, and file provider examples
• docs.md — official documentation links