basforge

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

    RU
    Cheat sheetHomelabTraefik

    Traefik labels: router, middleware, service

    The labels that connect a service to Traefik, and commands to check that Traefik understood them. memos in the examples is the router and service name; it’s the same in every line of one service.

    Connect a container

    Label What it does
    traefik.enable=true Traefik can see the container
    traefik.docker.network=proxy reach the container through the proxy network
    traefik.http.routers.memos.rule=Host(`memos.example.org`) which requests go to this router
    traefik.http.routers.memos.entrypoints=https listen on 443 only
    traefik.http.services.memos.loadbalancer.server.port=5230 the port inside the container

    Router rules

    Rule What it matches
    Host(`memos.example.org`) one name
    Host(`example.org`) || Host(`www.example.org`) two names, one service
    Host(`example.org`) && PathPrefix(`/api`) only paths under /api
    HostRegexp(`^.+\.example\.org$`) any subdomain; a Go regex in v3
    ClientIP(`192.168.0.0/16`) only requests from the home network

    If a request matches two routers, the one with the longer rule wins: Host(`example.org`) && PathPrefix(`/api`) beats Host(`example.org`) with no extra settings. To set it explicitly: traefik.http.routers.memos.priority=100, higher wins.

    TLS and certificates

    Label What it does
    traefik.http.routers.memos.tls=true turn on TLS for the router
    traefik.http.routers.memos.tls.certresolver=letsencrypt get the certificate from this resolver
    traefik.http.routers.memos.tls.domains[0].main=example.org a wildcard on the router; better on the entry point (Traefik and Let’s Encrypt)

    If the https entry point in traefik.yml sets http.tls.certResolver, you don’t need any of the three (traefik.yml block by block).

    Middleware

    Attach them to a router with one comma-separated line. The order in the line is the order of checks; a second middlewares label overwrites the first (A router’s middlewares go in one line).

    Label What it does
    traefik.http.routers.memos.middlewares=crowdsec@file,global-ratelimit@file ban first, then the rate limit
    traefik.http.middlewares.memos-auth.basicauth.users=admin:$$2y$$05$$… a login password
    traefik.http.middlewares.memos-ip.ipallowlist.sourcerange=192.168.0.0/16 allow only the home network
    traefik.http.middlewares.memos-strip.stripprefix.prefixes=/memos strip a prefix before the service
    traefik.http.middlewares.memos-hdr.headers.customrequestheaders.X-Forwarded-Proto=https a header for the service
    traefik.http.middlewares.memos-gz.compress=true compress responses
    traefik.http.middlewares.memos-rl.ratelimit.average=20 its own limit: 20 per second

    @file is a middleware from dynamic/; no suffix means one from labels. In v3 ipwhitelist was renamed to ipallowlist, and the old name no longer works.

    The Basic Auth password hash comes from htpasswd in the apache2-utils package:

    htpasswd -nB admin | sed -e 's/\$/\$\$/g'     # for a label right in compose: $ doubled
    htpasswd -nB admin                             # for .env: single $, the value in single quotes

    Why they differ — The $ sign.

    Service

    Label What it does
    traefik.http.services.memos.loadbalancer.server.port=5230 the app’s port
    traefik.http.services.memos.loadbalancer.server.scheme=https the service serves HTTPS itself
    traefik.http.services.memos.loadbalancer.passhostheader=false don’t pass the original Host to the service
    traefik.http.routers.memos.service=memos bind the router to the service explicitly

    If a container has one service, you can skip routers.<name>.service — Traefik binds them itself. With two or more services (two ports), write the binding explicitly.

    TCP: pass traffic through undecrypted

    Label What it does
    traefik.tcp.routers.app.rule=HostSNI(`app.example.org`) pick by the name in the TLS handshake
    traefik.tcp.routers.app.entrypoints=https on the same 443 as the sites
    traefik.tcp.routers.app.tls.passthrough=true don’t decrypt, forward as is
    traefik.tcp.services.app.loadbalancer.server.port=5558 where to forward

    With passthrough the service presents its own certificate, and HTTP middleware — bans, passwords — doesn’t apply to such a router.

    Apply and check

    Command What it does
    docker compose up -d apply labels: recreates the container
    docker inspect memos --format '{{json .Config.Labels}}' | jq which labels Traefik sees
    docker logs traefik --since 5m 2>&1 | grep -iE 'err|error' what Traefik complained about
    docker network inspect proxy --format '{{range .Containers}}{{.Name}} {{end}}' who’s on the shared network
    curl -sI https://memos.example.org | head -1 the router answers
    curl -s https://whoami.example.org | grep -i '^X-Real-Ip' which address the service sees

    docker compose restart doesn’t apply labels: it restarts the container with the old ones. You need up -d, which recreates the container if the compose file changed.