basforge

Search titles, text and the “If it doesn’t work” cases.

    RU
    OverviewHomelabTraefik

    Traefik: what it is and when to pick it

    Traefik is a reverse proxy: it takes every request to the server on ports 80 and 443 and hands it to a container by site name. It gets and renews Let’s Encrypt certificates on its own, and picks up new containers from labels in their compose files — no proxy config edits, no restart.

    What problem it solves

    One VPS runs several services in containers, each on its own port: memos notes on 5230, pulse monitoring on 7655, plus a website. From the outside you want something else: names on the regular port 443, a real certificate, and the services’ own ports closed.

    Without a proxy

    • http://203.0.113.10:5230 — memos
    • http://203.0.113.10:7655 — pulse
    • http://203.0.113.10:8080 — the site

    No HTTPS, every port open to the outside, each service with its own protection and logs, or none.

    With a reverse proxy

    • https://memos.example.org
    • https://pulse.example.org
    • https://example.org

    Only 80 and 443 open to the outside. Certificates, bans, admin passwords and the request log — in one place.

    Only one program on a server can hold port 443. So one goes in front: it takes every request, looks at which name is being asked for, and passes the request to the right container. That’s a reverse proxy. Since all traffic goes through it, it’s also where the shared pieces live: certificates, the HTTP-to-HTTPS redirect, bans on attacking addresses, admin passwords, rate limits, and one log for all services.

    There are many reverse proxies; the comparison is below. What sets Traefik apart is that it takes routes from Docker itself: a service declares its name with labels in its own compose file, and Traefik sees it as soon as the container starts.

    A request’s path: entry point, router, middleware, service

    The whole config rests on these four concepts. A request passes them in order:

    browser · https://memos.example.org

    1. Entry pointhttps · :443A port Traefik listens on. It accepts the connection and presents the certificate; the shared HTTP redirect lives here too.
    2. RouterHost(`memos.example.org`)A rule for “which requests are mine”. If no router matches, Traefik answers 404 page not found.
    3. Middlewarecrowdsec, ratelimitChecks along the way, in the listed order: a ban gives 403, a rate limit 429; passwords, headers.
    4. Servicememos:5230Where to send it: the container’s address and port. With several containers Traefik splits requests between them.

    memos container · proxy network · port not published

    Two kinds of config

    Traefik’s settings come in two parts with different rules. Most “why didn’t it apply” questions come from here.

    Static

    traefik.yml
    • Defines entry points, where routes come from, certificates, logs, plugins.
    • Applied only at startup: a change means restarting Traefik, and every site blinks.
    • ${…} variables aren’t substituted (traefik.yml doesn’t substitute variables).

    Dynamic

    labels, dynamic/*.yml
    • Defines routers, middleware, services, TLS options.
    • Applied live: Traefik watches Docker and the files.
    • Compose substitutes variables in labels.

    Traefik gets dynamic config from providers. On a single server with compose, two are enough: docker reads the labels of running containers through docker.sock, and file reads YAML files from the dynamic/ directory. That’s where you put what many services need at once: the shared ban middleware, rate limits, TLS options. There are also providers for Kubernetes, Swarm, Consul and others.

    An object’s name carries its provider as a suffix: crowdsec@file is a middleware from a file, memos@docker a router from labels. A reference to an object from another provider needs the suffix; otherwise Traefik looks for it in its own provider and doesn’t find it.

    Where it’s used

    The main case

    Your own server with services in Docker

    Each stack in /opt/<name>/ declares its name and protection in its own compose file. Remove the stack and the route goes with it.

    Several domains on one server

    A wildcard certificate for each domain is requested on the entry point and covers all subdomains at once (Traefik and Let’s Encrypt).

    A log of every request

    The JSON access log is read by CrowdSec, vector and Loki (Traefik logs).

    TCP services by name

    Sometimes traffic has to pass through as is, without decryption: a TCP router with HostSNI and tls.passthrough picks the recipient by the name in the TLS handshake on the same port 443.

    Kubernetes and Swarm

    An Ingress and Gateway API controller, installed by default in k3s. Ingress NGINX stopped getting updates in March 2026, and some clusters are moving off it.

    Other ways to solve it

    The alternatives are described from their documentation as of October 2026 and weren’t tested on a server.

    Where routes live Certificates Sees containers
    Traefik labels in each service’s compose file, plus YAML files Let’s Encrypt built in: HTTP-01, TLS-ALPN-01, DNS-01; Cloudflare and other DNS providers in the stock image yes
    Caddy one Caddyfile, 2–3 lines per site: memos.example.org { reverse_proxy memos:5230 } HTTPS by default for any name in the config, Let’s Encrypt and ZeroSSL; wildcard only with a build for your DNS provider via the third-party caddy-docker-proxy
    nginx server { … } files, applied with nginx -s reload separately: certbot or acme.sh with its own timer no
    Nginx Proxy Manager a web UI on port 81 over nginx; settings in its SQLite database Let’s Encrypt with a button in the UI no
    HAProxy haproxy.cfg: frontends and backends by hand ACME since 3.2 (HTTP-01), DNS-01 since 3.3 via the Data Plane API no
    If… Use
    services live in Docker, come and go, and you want the route next to the service Traefik
    two or three sites and you want one short file Caddy
    nginx is already there, or you also need a static file server with cache tuning nginx + certbot
    you won’t write configs by hand and have only a few services; settings live in a database you can’t put in git (Server configs in git) Nginx Proxy Manager
    you balance load across many servers and fine-tune TCP HAProxy

    What you get and what it costs

    What you get

    • The route lives next to the service. A new stack brings its own labels; the shared proxy config stays untouched.
    • No restarts. Traefik listens to Docker events and the dynamic/ directory and rebuilds routes at most once every 2 s (providersThrottleDuration). Other sites aren’t interrupted.
    • Certificates on its own. It obtains them, stores them in acme.json and renews 30 days before expiry. A wildcard through Cloudflare works with the official traefik:v3.7 image, no custom build (Traefik and Let’s Encrypt).
    • Middleware out of the box: passwords, rate limits, redirects, headers, IP allowlists, compression. Plugins add what’s missing, such as the CrowdSec bouncer (CrowdSec with Traefik behind Cloudflare).
    • A JSON log — a ready source for CrowdSec and Loki (Traefik logs).

    What it costs

    • Nobody checks the labels. Traefik silently accepts a typo in a router name and creates another router (Middleware on a missing router), and a second label with the same key overwrites the first (A router’s middlewares go in one line). The error shows only in the dashboard or the log.
    • The config is spread across stacks. To answer “what’s open to the outside right now”, you go through every compose file or turn on the dashboard.
    • Two kinds of config with different rules: the static one only via restart and without variables (traefik.yml doesn’t substitute variables). The first service takes longer to bring up than in Caddy, where two lines suffice.
    • It needs docker.sock, and socket access is root on the host (docker.sock).
    • Upgrades break things. v3 changed rule syntax: HostRegexp now uses Go regexes, Headers became Header. With Docker 29, Traefik before 3.6.1 stopped seeing containers. So pin the minor version in the tag: traefik:v3.7.

    Where to start

    If it doesn’t work

    A blank 404 page not found instead of the site

    Cause
    No router matched: the container lacks traefik.enable=true (with exposedByDefault: false Traefik doesn’t see it without that), there’s a typo in Host, the container isn’t running, or the router was disabled by an error — for example, a reference to a middleware that doesn’t exist.
    Fix
    Check docker logs traefik --since 10m 2>&1 | grep -iE 'err|error' and compare the name in the rule with the address bar.

    The browser complains about the certificate, which says TRAEFIK DEFAULT CERT

    Cause
    There’s no matching certificate, so Traefik served its self-signed one: port 80 is closed for HTTP-01, the DNS token lacks permissions, or a Let’s Encrypt limit was hit (5 failed validations per name per hour).
    Fix
    Check docker logs traefik 2>&1 | grep -i acme | tail -20; details — Traefik and Let’s Encrypt.

    Gateway Timeout after about 30 seconds

    Cause
    Traefik knows the container but can’t reach it: the container isn’t on the shared proxy network, or it’s on several networks and Traefik picked the wrong one. 30 s is the default dialTimeout.
    Fix
    Add the container to the proxy network and name it explicitly: traefik.docker.network=proxy.

    Bad Gateway right away

    Cause
    The network is fine, but nothing listens on that port: loadbalancer.server.port is wrong, or the service inside the container isn’t up yet.
    Fix
    Compare the port with the image’s documentation and look at the service’s docker logs.

    After a Docker upgrade every site returns 404, and Traefik’s log says client version 1.24 is too old

    Cause
    Docker 29 raised the minimum API version to 1.44, while Traefik before 3.6.1 negotiates 1.24.
    Fix
    Use traefik:v3.6.1 or newer: 3.6.1 added API version negotiation.

    A change in traefik.yml has no effect

    Cause
    Traefik reads the static config only at startup.
    Fix
    docker compose restart traefik.

    A large upload breaks off at about one minute

    Cause
    The entry point’s default readTimeout is 60 s — Traefik must read the whole request, body included, within that time.
    Fix
    Raise transport.respondingTimeouts.readTimeout on the entry point (traefik.yml block by block) and restart Traefik.