Skip to content
local-cert
Browse the documentation

Traefik

Traefik (v2 and v3) supports a custom CA and EAB in its certificate resolvers. All you need is to declare one that points to local-cert.

ValueWhere to find itIn this guide
ACME directoryfixed for each instancehttps://certs.example.com/acme/directory
Key ID (kid)Keys & access → EAB credentialseab_XXXXXXXXXXXXXXXX
HMAC keyshown only once, at creationCLE_HMAC

1. Declare the resolver

In the static configuration, as a file:

traefik.yml
entryPoints:
  web:
    address: ":80"
  websecure:
    address: ":443"

certificatesResolvers:
  localcert:
    acme:
      caServer: https://certs.example.com/acme/directory
      email: ops@example.com
      storage: /letsencrypt/localcert.json
      eab:
        kid: eab_XXXXXXXXXXXXXXXX
        hmacEncoded: CLE_HMAC
      httpChallenge:
        entryPoint: web

or as arguments, for a container:

docker-compose.yml (excerpt)
services:
  traefik:
    image: traefik:v3
    command:
      - --entrypoints.web.address=:80
      - --entrypoints.websecure.address=:443
      - --providers.docker=true
      - --certificatesresolvers.localcert.acme.caserver=https://certs.example.com/acme/directory
      - --certificatesresolvers.localcert.acme.email=ops@example.com
      - --certificatesresolvers.localcert.acme.storage=/letsencrypt/localcert.json
      - --certificatesresolvers.localcert.acme.eab.kid=eab_XXXXXXXXXXXXXXXX
      - --certificatesresolvers.localcert.acme.eab.hmacencoded=CLE_HMAC
      - --certificatesresolvers.localcert.acme.httpchallenge.entrypoint=web
    volumes:
      - ./letsencrypt:/letsencrypt
      - /var/run/docker.sock:/var/run/docker.sock:ro

2. Use it on a router

service labels
labels:
  - traefik.enable=true
  - traefik.http.routers.nas.rule=Host(`nas.home.example.com`)
  - traefik.http.routers.nas.entrypoints=websecure
  - traefik.http.routers.nas.tls.certresolver=localcert

Traefik requests the certificate the first time the router starts, then renews it on its own (30 days before expiry by default).

Good to know

  • The entrypoint named in httpChallenge must exist, but it will receive no validation request: there is no need to expose it outside the LAN.
  • Issuance takes one to three minutes. In the meantime Traefik serves its default certificate; this is normal.
  • For a wildcard, declare the names on the router with tls.domains[0].main / sans. If Traefik refuses the wildcard over HTTP-01, issue it through the API.
  • On failure, Traefik's logs at DEBUG level reproduce the ACME error returned by local-cert — see the troubleshooting table in ACME server.