Topic cluster
Reverse proxy configuration
nginx, HAProxy, Envoy, Caddy and Traefik: routing semantics, upstream selection, health checks, WebSockets, gRPC and session affinity, compared honestly.
A reverse proxy is the piece of infrastructure with the highest ratio of "looks simple" to "has surprising semantics". Two lines of configuration decide whether a path prefix is stripped, whether a WebSocket survives, whether a failed backend is retried, and whether the application ever learns who the client was.
This cluster covers the five reverse proxies most teams actually run, with an emphasis on the behaviour that differs between them rather than a restatement of each manual.
Choosing#
nginx vs HAProxy vs Envoy vs Caddy vs Traefik is the decision page. The short form:
- nginx if you also serve static content and want a configuration language your whole team already reads.
- HAProxy if load balancing correctness, L4 work and runtime control without reloads matter most.
- Envoy if you need dynamic configuration, first class gRPC and deep observability, and can afford the operational surface.
- Caddy if you want automatic HTTPS and the smallest possible operational footprint.
- Traefik if your routing should be derived from container or Kubernetes metadata rather than written by hand.
Per proxy#
nginx as a reverse proxy is the longest of these, because nginx has the most defaults that surprise people and the most configuration that has to be written by hand. The others follow the same shape: HAProxy, Envoy, Caddy and Traefik.
The behaviours that catch everyone#
- Path prefix handling. nginx proxy_pass and the trailing slash is the canonical example, and the proxy_pass simulator will tell you what your own configuration does.
- Protocol upgrades. WebSockets and gRPC both need explicit configuration in some proxies and none at all in others.
- Failure handling. Health checks and upstream failover covers the gap between "the backend is down" and "the proxy noticed".
- State. Sticky sessions explains when affinity is a legitimate optimisation and when it is a bug you have decided to keep.
Every guide in this cluster#
- Caddy reverse proxyCaddy's reverse_proxy directive, automatic HTTPS, load balancing and health checks, the handle vs handle_path trap, and Caddy versus nginx defaults.
- Envoy listeners, routes and clustersHow Envoy's listener, filter chain, route table and cluster model fits together, what xDS does, the full timeout ladder, and the response flag table for debugging.
- gRPC through a reverse proxyWhy gRPC needs end-to-end HTTP/2, how trailers and buffering break naive proxies, config for nginx, Envoy, HAProxy and Traefik, and why L4 balancing pins RPCs
- HAProxy configuration for HTTP reverse proxyingHow HAProxy sections, rule ordering, timeouts and the runtime API fit together, with a production-shaped config and a timeout-to-log-flag lookup table.
- Health checks and upstream failoverActive vs passive checks across nginx, HAProxy, Envoy, Traefik and Caddy, why deep health endpoints cause total outages, and the correct draining order.
- nginx proxy_pass and the trailing slashThe rule that decides the upstream URI. proxy_pass with a URI part replaces the matched location prefix; without one it forwards the request URI as sent.
- nginx as a reverse proxy: a complete configurationServer selection, location precedence, the header block every proxy needs, upstream tuning and reload semantics, and the defaults that break modern backends.
- nginx vs HAProxy vs Envoy vs Caddy vs TraefikA decision framework, a 19-row capability matrix and a defaults table for choosing between nginx, HAProxy, Envoy, Caddy and Traefik, plus what each one is bad at.
- Sticky sessions and session affinityCookie insertion, source IP hashing and consistent hashing compared across five proxies, with the security, autoscaling and draining costs of affinity.
- Traefik routers, services and middlewaresHow Traefik entryPoints, routers, services, middlewares and providers fit together, v2 to v3 rule syntax changes, Docker label config, ACME storage and the failure modes.
- WebSockets through a reverse proxyThe RFC 6455 handshake, why proxies strip Upgrade and Connection, config for nginx, HAProxy, Caddy, Traefik and Envoy, and the timeouts that kill sockets.