loadbalancer/README.md

Traefik TCP Load Balancer

Docker Compose deployment for Traefik used as a TCP load balancer with TLS passthrough.

What it does

• publishes 443/tcp on the Docker host;
• publishes 80/tcp on the Docker host for HTTP-01 certificate challenges;
• forwards TCP TLS traffic to backend IP addresses and ports;
• leaves SSL certificates and private keys on the backends;
• stores Traefik configuration in the host ./config directory;
• uses the Traefik file provider, without mounting the Docker socket.

Configuration

Add or edit one file per site under config/dynamic/. For example, config/dynamic/lab-younerd.yml contains:

http:
  routers:
    lab-yourdomain-http:
      entryPoints:
        - web
      rule: "Host(`lab.yourdomain.tld`)"
      service: lab-yourdomain-http

  services:
    lab-yourdomain-http:
      loadBalancer:
        healthCheck:
          path: "/"
          hostname: "lab.yourdomain.tld"
          interval: "10s"
          timeout: "3s"
        servers:
          - url: "http://127.0.0.1:8080"

tcp:
  routers:
    lab-yourdomain-tls:
      entryPoints:
        - tls
      rule: "HostSNI(`lab.yourdomain.tld`)"
      service: lab-yourdomain-tls
      tls:
        passthrough: true

  services:
    lab-yourdomain-tls:
      loadBalancer:
        healthCheck:
          interval: "10s"
          timeout: "3s"
        servers:
          - address: "127.0.0.1:8443"

HostSNI(...) matches the hostname sent by the client during the TLS handshake. This deployment uses host networking so Traefik can reach services bound to the Docker host loopback address, such as 127.0.0.1:8443.

HTTP-01 certificate challenges use normal HTTP routing on port 80, not SNI. The included example forwards:

lab.yourdomain.tld -> 127.0.0.1:8080
www.yourdomain.tld -> 127.0.0.1:9080

Adjust 8080 and 9080 to the local ports where the backend HTTP service is listening. The full HTTP request is forwarded so the backend can handle redirects and ACME challenge paths.

Each backend service includes health checks. TCP checks verify that the TLS port accepts connections; HTTP checks call / with the configured hostname and treat successful or redirect responses as healthy.

Run

Validate the Compose file:

docker compose config

Start Traefik:

docker compose up -d

View logs:

docker compose logs -f traefik

Stop the service:

docker compose down

Documentation

• Architecture: docs/architecture.md
• Deployment: docs/deployment.md
• Operations: docs/operations.md
• Security: docs/security.md
• Testing: docs/testing.md
• Runbook: docs/runbook.md
• ADR: docs/adr/0001-traefik-tcp-tls-passthrough.md