loadbalancer/docs/architecture.md

Architecture

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

Components

• compose.yaml: defines the Traefik container, host networking, 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/*.yml: dynamic per-site HTTP 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. Traefik receives the connection directly through host networking on 443/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. Traefik receives the request directly through host networking on 80/tcp.
3. Traefik matches the HTTP Host(...) router.
4. Traefik forwards the full HTTP request to the configured local backend so that backend redirects and ACME challenge handling remain in one place.

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 with network_mode: host. Backends are external to this Compose stack and can be reached on host loopback addresses such as 127.0.0.1:8443.

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