From 26843f5b88b5aeb5bf5af72912fd26c23aee6efa Mon Sep 17 00:00:00 2001 From: Pieter Hollander Date: Wed, 18 Feb 2026 18:29:20 +0100 Subject: [PATCH] Simplify reverse proxy hairpin NAT setup with host-gateway Replace static IP assignment for Traefik with Docker's built-in host-gateway, which is simpler and survives container restarts. --- .../migration/enable-reverse-proxy.mdx | 33 +++---------------- 1 file changed, 4 insertions(+), 29 deletions(-) diff --git a/src/pages/selfhosted/migration/enable-reverse-proxy.mdx b/src/pages/selfhosted/migration/enable-reverse-proxy.mdx index 359853fa..6adf690b 100644 --- a/src/pages/selfhosted/migration/enable-reverse-proxy.mdx +++ b/src/pages/selfhosted/migration/enable-reverse-proxy.mdx @@ -323,38 +323,17 @@ traefik.http.routers.netbird-grpc.rule=Host(`netbird.example.com`) && (PathPrefi Without the `/management.ProxyService/` route, the proxy will fail to register with the management server. -### 2. Fix the Traefik container IP for hairpin NAT +### 2. Route the Proxy container's traffic through Traefik using `host-gateway` -When the proxy connects to your management domain through Traefik, the DNS resolution inside the Docker network must point to the Traefik container. This is done via an `extra_hosts` entry in the proxy service, but the IP address must match Traefik's actual IP. +When the Proxy container connects to your management domain, it needs to reach Traefik rather than resolving the domain to an external IP. Without this, the request would leave the Docker host and come back in — a hairpin NAT scenario that often fails or adds unnecessary latency. By adding an `extra_hosts` entry that maps your domain to `host-gateway`, Docker resolves it to the host's internal IP, keeping traffic local and routing it directly through Traefik. -To ensure a stable IP, assign a static IP to the Traefik container within your Docker network: - -```yaml -# In your docker-compose.yml - -networks: - netbird: - driver: bridge - ipam: - config: - - subnet: 172.30.0.0/24 - gateway: 172.30.0.1 - -services: - traefik: - # ...existing traefik config... - networks: - netbird: - ipv4_address: 172.30.0.10 -``` - -Then add the `extra_hosts` entry to the proxy service referencing that IP: +Add an `extra_hosts` entry to the proxy service: ```yaml proxy: # ...existing proxy config... extra_hosts: - - "netbird.example.com:172.30.0.10" + - "netbird.example.com:host-gateway" ``` Replace `netbird.example.com` with your actual management domain. @@ -393,10 +372,6 @@ NB_PROXY_MANAGEMENT_ADDRESS=https://netbird.example.com:443 # Do NOT set NB_PROXY_ALLOW_INSECURE when connecting over TLS through Traefik ``` - -If you do not assign a static IP to Traefik, Docker may assign a different IP on container restart, and the `extra_hosts` entry will silently point to the wrong address. Always configure a fixed subnet and static IP when using this approach. - - ## For users not on Traefik If your self-hosted deployment currently uses Nginx, Caddy, or another reverse proxy, you'll need to switch to Traefik before enabling the Reverse Proxy feature. See the [Traefik setup instructions](/selfhosted/reverse-proxy#traefik) for a step-by-step guide on configuring Traefik for your NetBird deployment.