loadbalancer/docs/architecture.md

Architecture

This project runs Traefik Proxy as a Dockerized TCP load balancer.

Components

• compose.yaml: defines the Traefik container, published port, host-based configuration volume, container hardening, and healthcheck.
• config/traefik.yml: static Traefik configuration for HTTP, TCP TLS, ping, file provider, and logging.
• config/dynamic/tcp-services.yml: dynamic HTTP challenge routers, TCP routers, and backend load-balancer services.

Data flow

1. A client opens a TLS connection to the Docker host on 443/tcp.
2. Docker forwards the connection to Traefik on container port 8443/tcp.
3. Traefik matches the TCP router using HostSNI(*).
4. Traefik forwards the unchanged TCP stream to one configured backend IP address and port.
5. The selected backend terminates TLS and presents its own SSL certificate.

For HTTP-01 certificate validation:

1. Let's Encrypt opens an HTTP connection to the Docker host on 80/tcp.
2. Docker forwards the request to Traefik on container port 8080/tcp.
3. Traefik matches the HTTP Host(...) and PathPrefix('/.well-known/acme-challenge/') router.
4. Traefik forwards the request to the configured local challenge responder.

Persistence

Traefik configuration is stored in the host ./config directory and mounted read-only at /etc/traefik.

No certificates, private keys, application data, or Docker socket are mounted into the Traefik container.

Deployment topology

Traefik runs as one Docker container on the load-balancer host. Backends are external to this Compose stack and must be reachable from the container through their configured IP addresses and ports. The Compose service defines host.docker.internal through Docker's host-gateway feature for backends that listen on the Docker host itself.

See docs/adr/0001-traefik-tcp-tls-passthrough.md for the design decision.