Traefik
Overview
Section titled “Overview”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
Installation
Section titled “Installation”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 EncryptdashboardHost- Dashboard hostname; unset means no dashboard route (see Dashboard)
Configuration
Section titled “Configuration”Traefik automatically discovers services with public_hosts:
# In app.yamlservices: web: public_hosts: - myapp.example.comSHC generates Traefik labels automatically:
- Router rules
- TLS configuration
- Certificate resolver
TLS Defaults
Section titled “TLS Defaults”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.
DNS Providers
Section titled “DNS Providers”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.
DNS-01 propagation pre-check
Section titled “DNS-01 propagation pre-check”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:
| Var | Default | Effect |
|---|---|---|
dns01.checkResolvers | 1.1.1.1:53,8.8.8.8:53 | Runs 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.checkDelay | 30s | Delays 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:
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
checkResolversat 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.1and8.8.8.8are unreachable and every check will time out. SetcheckResolversto 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.
Access log
Section titled “Access log”Traefik’s request log goes to the container’s stdout, and docker’s
json-file driver is what bounds it:
| Var | Default | Effect |
|---|---|---|
accessLog.enabled | true | Emit request lines at all. Traefik’s own log (errors, ACME, provider events) is unaffected either way. |
accessLog.maxSize | 10m | Per-file cap before docker rotates. |
accessLog.maxFiles | 3 | How many rotated files docker keeps. maxSize x maxFiles is the hard ceiling per node. |
shc config set modules.traefik.vars.accessLog.enabled falseshc config set modules.traefik.vars.accessLog.maxSize 50mRequest headers in the access log
Section titled “Request headers in the access log”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.
| Var | Default | Effect |
|---|---|---|
accessLog.headers.defaultMode | empty | keep, 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> | none | keep, 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.
shc config set modules.traefik.vars.accessLog.headers.defaultMode dropshc config set modules.traefik.vars.accessLog.headers.names.User-Agent keepshc config set modules.traefik.vars.accessLog.headers.names.Origin keepshc config set modules.traefik.vars.accessLog.headers.names.Cookie redactshc config set modules.traefik.vars.accessLog.headers.names.Authorization redactshc -t master update traefikHeader 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 falseif 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.
Integration with Other Apps
Section titled “Integration with Other Apps”Apps connect to Traefik via the traefik_access network:
shc install nextcloud -t <tenant> --stack cloud --expose cloud.example.comAccess public URL: https://cloud.example.com. Without --expose the app
gets no route and that URL answers 404.
Dashboard
Section titled “Dashboard”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:
shc config set modules.traefik.vars.dashboardHost traefik.corp.example.comshc -t master update traefikSHC 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.
Troubleshooting
Section titled “Troubleshooting”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