Skip to content
SHC Docs

Traefik

Traefik is a modern reverse proxy and load balancer.

Key features:

  • Automatic service discovery
  • Let’s Encrypt integration
  • HTTP/2 and gRPC support
  • Dashboard and metrics

shc init always installs SHC’s own Traefik into the master tenant, SHC’s own tenant, because nodes join the cluster through it on 443. It runs nowhere else, so there is nothing to install yourself.

Common variables:

  • email - Email for Let’s Encrypt
  • dashboardHost - Dashboard hostname; unset means no dashboard route (see Dashboard)

Traefik automatically discovers services with public_hosts:

# In app.yaml
services:
web:
public_hosts:
- myapp.example.com

SHC generates Traefik labels automatically:

  • Router rules
  • TLS configuration
  • Certificate resolver

TLS is only enabled when explicitly requested (for example via CLI flags). When enabled without an explicit mode, Traefik uses ACME HTTP-01 by default. DNS-01 is available when selected and a DNS provider is configured.

SHC manages DNS records for --expose (hostname) deployments using the resolved provider for that deployment scope. Traefik receives provider updates only when DNS providers are added, removed, or modified in SHC config.

Before telling the ACME CA that a DNS-01 challenge is ready, lego checks that the challenge TXT record is actually being served. Left to its defaults that check runs against the node’s own recursive resolver and fires roughly a second after the record is created, usually before the DNS provider’s edge serves it. The resolver answers NXDOMAIN and caches that negative for the zone’s SOA minimum (commonly 1800s), lego then polls the poisoned cache until the order times out, and Traefik re-poisons it on the next retry. The estate does not recover on its own: every DNS-01 issuance stays stuck until the negative cache expires.

Every DNS-01 certificate resolver SHC seeds therefore carries two settings:

VarDefaultEffect
dns01.checkResolvers1.1.1.1:53,8.8.8.8:53Runs the pre-check against these servers instead of the node’s own resolver, so a negative answer never contaminates the resolver everything else on the node shares.
dns01.checkDelay30sDelays the first pre-check query so the record is genuinely being served before anything asks for it. Costs its value once per ACME order, on the DNS-01 path only.

Both are ordinary install vars on the system Traefik stack, so they are overridable without forking the app:

Terminal window
shc config set modules.traefik.vars.dns01.checkResolvers "10.0.0.53:53"
shc config set modules.traefik.vars.dns01.checkDelay "60s"

The defaults assume a public zone. Change them when that is not your topology:

  • Split-horizon / internal DNS: point checkResolvers at the server that is authoritative for the zone being challenged. A public resolver answers for the public view and will disagree with the internal record.
  • Airgapped: 1.1.1.1 and 8.8.8.8 are unreachable and every check will time out. Set checkResolvers to the estate’s own authoritative nameserver (the in-estate PowerDNS / BIND / RFC2136 target the DNS-01 provider writes to).
  • Opt out: set either var to "". That key is then not emitted at all and Traefik keeps its stock behaviour.

A change to either var re-renders and restarts Traefik. Already-issued certificates live in the bind-mounted ACME storage and survive the restart.

Traefik’s request log goes to the container’s stdout, and docker’s json-file driver is what bounds it:

VarDefaultEffect
accessLog.enabledtrueEmit request lines at all. Traefik’s own log (errors, ACME, provider events) is unaffected either way.
accessLog.maxSize10mPer-file cap before docker rotates.
accessLog.maxFiles3How many rotated files docker keeps. maxSize x maxFiles is the hard ceiling per node.
Terminal window
shc config set modules.traefik.vars.accessLog.enabled false
shc config set modules.traefik.vars.accessLog.maxSize 50m

Request lines carry no request headers by default. Two vars turn them on, and with both unset the rendered Traefik project is byte-identical to a release without them, so setting nothing recreates nothing.

VarDefaultEffect
accessLog.headers.defaultModeemptykeep, drop or redact: what happens to a header names doesn’t list. Empty emits no fields block and Traefik logs no headers.
accessLog.headers.names.<Header>nonekeep, drop or redact for one header. One config row per header. Needs defaultMode.

They render into the static config as accessLog.fields.headers. redact writes the header’s name with the value REDACTED, so a log can show that a request carried a cookie or a bearer token without showing either.

Terminal window
shc config set modules.traefik.vars.accessLog.headers.defaultMode drop
shc config set modules.traefik.vars.accessLog.headers.names.User-Agent keep
shc config set modules.traefik.vars.accessLog.headers.names.Origin keep
shc config set modules.traefik.vars.accessLog.headers.names.Cookie redact
shc config set modules.traefik.vars.accessLog.headers.names.Authorization redact
shc -t master update traefik

Header names are written the way Go canonicalizes them (User-Agent, not user-agent), because that’s the key Traefik looks the request header up by. shc config set refuses a misspelled name or a mode outside the three, and the update refuses names without defaultMode before anything is rendered.

Why it is not a file. Traefik has no rotation for the access log. v3.6 ships --log.maxsize / --log.maxbackups / --log.maxage / --log.compress for its own log and nothing equivalent for accesslog, so a file-backed access log grows forever with nothing anywhere to stop it: measured at 402 MB on a live estate, with no /etc/logrotate.d entry, and (because the log volume had no backup converter) swept into every Traefik backup at that size. Docker’s log driver is the only rotation available at the packaging level, and it only applies to the container’s stdout.

Two consequences worth knowing:

  • Access lines share the stream with Traefik’s own log. They are emitted as JSON so the two halves stay machine-separable.
  • SHC’s collector tails container logs, so request lines now reach the estate’s log store instead of sitting in a file nobody read. Set accessLog.enabled false if that is not wanted.

Upgrading an existing estate leaves the old logs volume on disk; nothing writes to it any more, and it is safe to prune.

Apps connect to Traefik via the traefik_access network:

Terminal window
shc install nextcloud -t <tenant> --stack cloud --expose cloud.example.com

Access public URL: https://cloud.example.com. Without --expose the app gets no route and that URL answers 404.

The dashboard has no route until you give it a host. It is then served behind SSO (platform admins and master-tenant users holding stack:traefik:use), and behind the LAN allowlist when lanEnforcement resolves to allowlist for master/traefik/default:

Terminal window
shc config set modules.traefik.vars.dashboardHost traefik.corp.example.com
shc -t master update traefik

SHC publishes the host’s DNS record and adds it to the forward-auth redirect URIs. Unset the key and update again to take the route away.

debug: true only raises the log level to DEBUG. It never turns on Traefik’s insecure API (api.insecure), so this host is the only way in.

Common issues:

Problem: SSL certificate not issued Solution: Verify DNS points to server, check email configuration

Problem: Service not accessible Solution: Check the deployment is healthy with shc status myapp, then inspect the rendered Traefik labels via shc inspect myapp

Problem: Dashboard shows 404 Solution: Check shc config get modules.traefik.vars.dashboardHost, then shc -t master update traefik