Traefik — container-native reverse proxy · Docker & Containers

nginx and HAProxy both have the same blind spot: they learn about backends from a file you maintain, or from DNS. Traefik removes the file. It connects to the Docker daemon’s API, subscribes to the event stream, reads labels off every container, and rebuilds its routing table whenever anything changes — with no reload and no restart.

For a host where containers are created and destroyed on every deploy that is the right shape. It also means the proxy holds a connection to the Docker daemon, and that is not a small thing. This lesson covers both, in that order, because you should not deploy the first without having decided about the second.

The three objects Traefik routes with

Every label you will write names one of these:

Object	Answers	Label prefix
EntryPoint	which port and protocol traffic arrives on	static config only, not a label
Router	which requests match, and on which entrypoint	`traefik.http.routers.<name>.`
Middleware	what to do to a matching request before forwarding	`traefik.http.middlewares.<name>.`
Service	which container and port to forward to, and how to check it	`traefik.http.services.<name>.`

EntryPoints live in static configuration because they are process startup decisions — you cannot open a listening port by adding a label to some other container. Everything else is dynamic.

A configuration you can run

Configuration changecompose.yaml— Annotated. Note exposedByDefault=false and the pinned minor version.

services:
traefik:
  image: traefik:v3.6
  restart: unless-stopped
  command:
    # --- Providers -------------------------------------------------
    - "--providers.docker=true"
    # Opt-in routing. Without this, EVERY container on the host with a
    # resolvable name gets a router, including your database.
    - "--providers.docker.exposedByDefault=false"
    # Traefik and the apps share this network; see the 502 section.
    - "--providers.docker.network=edge"

    # --- EntryPoints -----------------------------------------------
    - "--entryPoints.web.address=:80"
    - "--entryPoints.websecure.address=:443"
    - "--entryPoints.web.http.redirections.entryPoint.to=websecure"
    - "--entryPoints.web.http.redirections.entryPoint.scheme=https"
    - "--entryPoints.web.http.redirections.entryPoint.permanent=true"

    # Trust X-Forwarded-* only from the addresses genuinely in front
    # of us. Omitting this means Traefik ignores them, which is the
    # safe default; 'insecure' would trust anyone and is not used here.
    - "--entryPoints.websecure.forwardedHeaders.trustedIPs=192.0.2.0/24"

    # Timeouts. Defaults: read 60s, write 0 (none), idle 180s.
    - "--entryPoints.websecure.transport.respondingTimeouts.readTimeout=60s"
    - "--entryPoints.websecure.transport.respondingTimeouts.idleTimeout=180s"
    # Keep taking requests for 5s after SIGTERM so an upstream LB can
    # notice, then give in-flight requests 15s to finish.
    - "--entryPoints.websecure.transport.lifeCycle.requestAcceptGraceTimeout=5s"
    - "--entryPoints.websecure.transport.lifeCycle.graceTimeOut=15s"

    # --- ACME ------------------------------------------------------
    - "--certificatesresolvers.le.acme.email=ops@example.com"
    - "--certificatesresolvers.le.acme.storage=/letsencrypt/acme.json"
    - "--certificatesresolvers.le.acme.tlschallenge=true"

    - "--log.level=INFO"
    - "--accesslog=true"
  ports:
    - "80:80"
    - "443:443"
  volumes:
    # Read the socket security section before you keep this line.
    - /var/run/docker.sock:/var/run/docker.sock:ro
    - letsencrypt:/letsencrypt
  networks: [edge]

web:
  image: nginx:1.29
  restart: unless-stopped
  networks: [edge]
  labels:
    - "traefik.enable=true"
    - "traefik.http.routers.web.rule=Host(`app.example.com`)"
    - "traefik.http.routers.web.entrypoints=websecure"
    - "traefik.http.routers.web.tls.certresolver=le"
    # Required whenever the container exposes more than one port,
    # and good practice always.
    - "traefik.http.services.web.loadbalancer.server.port=80"
    # Active health check. Traefik stops routing to a container that
    # fails this - which Docker's own HEALTHCHECK does not do.
    - "traefik.http.services.web.loadbalancer.healthcheck.path=/healthz"
    - "traefik.http.services.web.loadbalancer.healthcheck.interval=10s"
    - "traefik.http.services.web.loadbalancer.healthcheck.timeout=3s"

volumes:
letsencrypt:

networks:
edge:

exposedByDefault is true, and that default is the wrong one for a shared host

Left at its default, Traefik creates a router for every container it can see, using defaultRule — which is Host(`{{ normalize .Name }}`) — as the rule. On a host running a database, a Redis cache and an internal admin tool alongside your web application, that quietly publishes routers for all of them.

Whether any of those routers is reachable depends on your DNS and your entrypoints, so this is not automatically an exposure. It is a configuration you did not write, on an internet-facing proxy, and “probably not reachable” is not a control.

Set --providers.docker.exposedByDefault=false and add traefik.enable=true to the containers that should be routable. Make it the first line of every Traefik deployment.

The Docker socket is the whole security story

The brief version, stated plainly because it is routinely understated:

Any process that can talk to the Docker API can become root on the host. It can create a container with --privileged, or one that bind-mounts / and writes to /etc/shadow, or one that mounts the host PID namespace. The Docker socket is not “read access to some container metadata”; it is a root shell with extra steps.

Traefik’s own documentation quotes the Docker security guidance directly: only trusted users should be allowed to control your Docker daemon, and notes that “if Traefik is attacked, then the attacker might get access to the underlying host.”

Configuration changethe mitigation: a filtering socket proxy— Traefik never touches the real socket. Only the listed API groups are allowed.

services:
dockersocket:
  image: tecnativa/docker-socket-proxy:0.3.0
  restart: unless-stopped
  environment:
    # Default-deny. Everything not listed here returns 403.
    CONTAINERS: 1
    EVENTS: 1
    VERSION: 1
    PING: 1
    # Explicitly denied - these are the dangerous ones.
    POST: 0
    EXEC: 0
    IMAGES: 0
    VOLUMES: 0
    NETWORKS: 0
  volumes:
    - /var/run/docker.sock:/var/run/docker.sock:ro
  # Deliberately NOT published to the host. Internal network only.
  networks: [socket]

traefik:
  image: traefik:v3.6
  command:
    - "--providers.docker=true"
    - "--providers.docker.endpoint=tcp://dockersocket:2375"
    - "--providers.docker.exposedByDefault=false"
  networks: [socket, edge]
  # Note: no docker.sock mount at all.

networks:
socket:
  internal: true
edge:

POST: 0 is the line that matters. Container creation, exec, and every other state change is a POST, so denying the verb denies the escalation path even if a new endpoint appears in a future API version. internal: true on the network means the socket proxy has no route off the host at all.

This moves the trust from “Traefik and every dependency it ships” to “a 20 MB proxy whose only job is an allowlist”. That is not perfect — the socket proxy container itself still holds the real socket — but the container holding it is no longer the one exposed to the internet, which is the substantive change.

The two failures every Traefik deployment hits

404 page not found

Traefik answered, so Traefik is running and reachable. It has no router matching that request.

Read-only / Safediagnose a 404— Ask Traefik what routers it actually built, rather than what you think it built.

PROXY=traefik
SVC=web

# Did Traefik see the container at all, and did it accept the labels?
docker compose logs "$PROXY" | grep -i -E 'error|warn' | tail -n 20

# What the daemon is advertising for this container
docker inspect -f '{{json .Config.Labels}}' "$(docker compose ps -q "$SVC")" | tr ',' '\n' | grep traefik

In order of frequency, a 404 is:

traefik.enable=true missing, with exposedByDefault=false. The container is invisible.
The rule does not match. Host(`app.example.com`) is exact; www.app.example.com does not match it. The backticks inside the rule are Traefik’s own syntax and are mandatory.
The router is on the wrong entrypoint. Without traefik.http.routers.web.entrypoints=websecure, the router is attached to every default entrypoint, which is usually not what you want and occasionally publishes on :80 what you meant to publish only on :443.
A typo in the router name segment. routers.web.rule and routers.wed.entrypoints build two different routers, one with no rule and one with no entrypoint. Traefik logs this and carries on.

Bad Gateway / “service … has no server available”

The router matched. Traefik could not reach the container.

Traefik routes correctly and every request is a 502

The labels are right, the router appears in the logs, and every request comes back 502. docker exec into the app container and it serves perfectly on the port you named.

The cause is almost always networks, not ports. Traefik forwards to the container’s IP on a Docker network, which means Traefik must be attached to a network the target container is also on. If they share none, there is no route and the connection fails immediately.

The subtler version: the container is on two or more networks. Traefik then has to pick one, and its choice is arbitrary unless you tell it. If it picks the backend network that Traefik is not on, you get 502 for a container that is otherwise perfectly reachable — and the behaviour changes depending on the order networks were created, so it “worked on my machine” is literally true.

Two fixes, use both: set --providers.docker.network=edge as the default, and put traefik.docker.network=edge on any container that needs to differ.

The second-commonest cause is the port. Traefik guesses the port from the image’s EXPOSE when there is exactly one, and guesses wrong or refuses when there are several. Always write traefik.http.services.<name>.loadbalancer.server.port explicitly. It must be the port inside the container — the published host port is irrelevant, because Traefik does not go via the host.

Read-only / Safeprove the network path— Compare the networks each container is on before touching anything else.

PROXY=traefik
SVC=web

for c in "$PROXY" "$SVC"; do
printf '%s: ' "$c"
docker inspect -f '{{range $k, $v := .NetworkSettings.Networks}}{{$k}}={{$v.IPAddress}} {{end}}'   "$(docker compose ps -q "$c")"
done

# Can Traefik actually reach it on the port the label names?
docker compose exec -T "$PROXY" wget -qO- --timeout=3 "http://$SVC:80/healthz" && echo REACHABLE || echo UNREACHABLE

If the two containers share no network name, you have your answer without reading another log line.

ACME: the part that is genuinely easy, and the part that is not

Three challenge types, and the choice is dictated by your network rather than by preference:

Challenge	Needs	Use when
`tlschallenge`	inbound `:443` reachable from the internet	the common case
`httpchallenge` (with `.entrypoint=web`)	inbound `:80` reachable	`:443` is not free, or you need it before TLS is up
`dnschallenge`	API credentials for your DNS provider	wildcard certificates, or the host is not publicly reachable at all

Only dnschallenge can issue a wildcard, and only dnschallenge works for an internal host with no inbound path — which is the reason most people end up there eventually.

Rate-limited out of certificate issuance for a week

You iterate on the Compose file. Each docker compose down -v removes the volume holding acme.json, so each up requests a fresh certificate. After the fifth identical request Let’s Encrypt’s duplicate-certificate limit stops answering, and you cannot get a certificate for that name for seven days — on the domain you are trying to launch.

Two habits prevent it entirely:

Develop against staging. Add --certificatesresolvers.le.acme.caserver=https://acme-staging-v02.api.letsencrypt.org/directory while you iterate. Staging issues an untrusted certificate — your browser will complain, and that complaint is the signal that you are correctly pointed at staging. Remove the flag for production, and delete acme.json when you do, because the staging account and its certificates live in that file.
Never let acme.json live in an anonymous volume. A named volume or a bind mount survives down -v only if you are careful; a bind mount to a path you back up is the safer choice.

acme.json holds the account key and every private key Traefik has obtained. Traefik requires it to be mode 600 and refuses to start otherwise — which is a good check, and one people work around by loosening permissions instead of fixing ownership.

Configuration changeacme storage on a bind mount— Create it before first start so Traefik does not create it with an unexpected mode.

set -euo pipefail
ACME_DIR=/srv/traefik/letsencrypt

sudo install -d -m 0700 "$ACME_DIR"
sudo touch "$ACME_DIR/acme.json"
sudo chmod 0600 "$ACME_DIR/acme.json"

# Confirm before starting Traefik. Anything other than 600 fails at boot.
stat -c '%a %n' "$ACME_DIR/acme.json"

Verification that can fail

Read-only / Safethe routing table Traefik actually built— The API on the internal traefik entrypoint. Do not publish this port.

$ docker compose exec -T traefik wget -qO- http://localhost:8080/api/http/routers

[{"entryPoints":["websecure"],"service":"web@docker","rule":"Host(`app.example.com`)",
"status":"enabled","using":["websecure"],"name":"web@docker","provider":"docker"},
{"entryPoints":["websecure"],"service":"api@docker","rule":"PathPrefix(`/api`)",
"status":"disabled","error":["port is missing"],"name":"api@docker","provider":"docker"}]

Illustrative output

"status":"disabled" with an error array is the single most useful output in Traefik. A router that failed to build does not throw; it is recorded as disabled with a reason, and the reason is usually exactly the mistake. Requiring --api.insecure=true to reach this on a published port is the wrong trade — reach it from inside the container as above, or put the dashboard behind an authenticated router.

Read-only / Safefour checks that can fail— Configuration parse, router status, certificate issuer, backend reachability.

HOST=app.example.com

# 1. Does Traefik consider its own configuration valid?
docker compose exec -T traefik traefik --help >/dev/null && echo 'binary ok'
docker compose logs traefik | grep -iE 'command error|configuration error' && exit 1

# 2. Any router in an error state?
docker compose exec -T traefik wget -qO- http://localhost:8080/api/http/routers | grep -o '"status":"disabled"' | wc -l

# 3. Is the certificate real, or is it Traefik's self-signed placeholder?
echo | openssl s_client -connect "$HOST:443" -servername "$HOST" 2>/dev/null | openssl x509 -noout -issuer -subject -dates

# 4. End to end, following the redirect from :80
curl -sSIL "http://$HOST/" | grep -E '^HTTP/|^location:'

Check 3 is the one that matters. When ACME has not succeeded, Traefik serves a self-signed default certificate rather than failing — the site is reachable over HTTPS and every browser shows a warning. An issuer line reading CN = TRAEFIK DEFAULT CERT means ACME never completed, and the reason will be in the logs.

When Traefik is the right choice

Situation	Traefik	Note
Containers created and destroyed on every deploy	yes	this is the case it exists for
You want certificates without a second tool	yes	ACME is built in, including DNS-01 wildcards
The proxy must not talk to the Docker daemon	no	that connection is the product
Configuration must be reviewable in one diff	no	routing is scattered across every service’s labels
L4 / TCP load balancing to a database	limited	TCP routers exist but the model is HTTP-first; prefer HAProxy
The proxy should also serve static files	no	Traefik forwards; it does not serve content
A single, rarely changing set of backends	no	you get label indirection for a problem you do not have

The label model’s real cost shows up in review, not in operation: a routing change is a diff on an application service, so the question “what is routed on this host?” has no single file to answer it. The /api/http/routers endpoint is the answer, and it only exists at runtime.

What if the Traefik container is restarted while requests are in flight?

By default, graceTimeOut is 10 seconds: on SIGTERM Traefik stops accepting new connections immediately and gives in-flight requests up to 10 seconds to finish before exiting. Anything still running at 10 seconds is cut.

Three things follow, and the third is the one people miss:

Requests arriving during those 10 seconds are refused, because Traefik has already stopped accepting. If an upstream load balancer is still sending traffic to this host, those are dropped requests, not delayed ones. That is what lifeCycle.requestAcceptGraceTimeout exists for: it keeps accepting for a configured period before the grace period starts, so an upstream health check has time to notice and take the host out. It defaults to 0s, which means no such window.
Long-lived connections are the ones that get cut. A WebSocket or a streaming response has no natural end within 10 seconds, so graceTimeOut will always truncate it. Raising the value does not fix that; it only moves the cut.
Routing state rebuilds from scratch, and that is fine. Traefik keeps nothing on disk except acme.json. It reconnects to the event stream, re-reads every container’s labels, and reconstructs the same routers. There is no state to restore and no drain to undo — which is the flip side of having no runtime API to change state with in the first place.

To undo a bad label change, revert the label and docker compose up -d the affected service. Traefik picks it up from the event stream within a second; nothing about Traefik itself needs touching.

Knowledge check

Why this matters

Traefik is the only proxy in this part that removes work rather than moving it. There is no upstream file to keep in step with reality, no reload to remember, and no stale address to 502 on — because the source of truth for “what is running” is the same daemon that is actually running it.

The price is a trust relationship. A proxy that is reachable from the internet is holding a connection to the interface that controls the host, and the industry’s standard illustration of that risk — :ro on the socket mount — is decoration rather than a control. Run the socket proxy. It is fifteen lines of Compose and it converts “if Traefik is compromised, the host is compromised” into “if Traefik is compromised, an attacker can enumerate containers”, which is an entirely different incident.

Where next

Caddy takes the automatic-certificate idea further than Traefik does — HTTPS is not a feature you enable, it is the default you would have to work to turn off — while going back to a static configuration file.