Traefik
Docker-label auto-discovery proxy — OKE_PROXY_HOST, OKE_PROXY_ACME_EMAIL, socket-proxy, ACME volume.
Traefik discovers app replicas from Docker labels instead of a static upstream, so
docker compose up --scale app=N load-balances without reconfiguring the proxy.
The one rule
Traefik never mounts the raw Docker socket. A filtered tecnativa/docker-socket-proxy companion
exposes only containers / events / ping / version / networks on the internal compose network.
Quick start
Pin the proxy
images: {
proxy: "traefik:v3.7",
},Hostname + ACME email
OKE_PROXY_HOST=app.example.com
OKE_PROXY_ACME_EMAIL=admin@example.comOKE_PROXY_ACME_EMAIL defaults to admin@example.com if unset — set a real mailbox
before production ACME.
Scale the app
docker compose … up -d --scale app=3App labels: traefik.http.routers.app.rule=Host(...), TLS cert resolver letsencrypt,
load-balancer port 6530.
Required env
| Variable | Required? | Meaning |
|---|---|---|
OKE_PROXY_HOST | Yes (production) | Host rule + ACME identity; default localhost |
OKE_PROXY_ACME_EMAIL | Yes (production) | Let's Encrypt account email |
allowedHosts (config) | Production | Must include the public hostname |
Data and backup
| Volume | Path | What it stores |
|---|---|---|
proxy-letsencrypt | /letsencrypt | acme.json — certificates + ACME account |
| Socket proxy only | /var/run/docker.sock:ro | Only the socket-proxy companion mounts this |
Backup means: preserve the proxy-letsencrypt volume (especially acme.json). Losing
it forces re-issuance and can hit Let's Encrypt rate limits. The socket-proxy has no
durable state.
Production note
Security posture is intentional: Traefik talks to tcp://socket-proxy:2375 with a
filtered API (CONTAINERS, EVENTS, PING, VERSION, NETWORKS only). Never mount
raw docker.sock on Traefik — keep the socket-proxy companion in front.
HTTP entrypoint redirects to websecure. For a single instance with no scale plans,
Caddy is simpler (no labels, no companion).
What the recipe configures
| Field | Value |
|---|---|
| Ports | 80 + 443 |
| Providers | Docker via socket-proxy, exposedbydefault=false |
| Companion | tecnativa/docker-socket-proxy:v0.5.0 |
| Healthcheck | traefik healthcheck --ping, every 10s, 5 retries |
Troubleshooting
Usually socket-proxy is down, or app lacks Traefik labels. Confirm
depends_on: socket-proxy and that compose.proxy.yml merged the app labels.
Logs showing Docker provider connection errors point at the socket-proxy, not Traefik config syntax.
oke dev starts infra only; the app stays on the host at :6530.
Traefik labels apply when app is in Compose — use oke docker for that.
Re-run oke dev after upgrading so compose drops the label-only app.
Replace the default admin@example.com with a real OKE_PROXY_ACME_EMAIL. If you wiped
proxy-letsencrypt, you may be rate-limited — restore acme.json from backup instead of
re-issuing repeatedly.
Learn more
- Caddy — simpler single-instance HTTPS edge
- nginx — static HTTP reverse proxy
- Security —
allowedHosts