Homelab/docs/guides/DNS_SETUP.md

DNS Configuration Guide (Cloudflare & Pi-hole)

To ensure reliable connectivity to your Traefik Swarm services both internally and externally, a "Split Horizon" DNS strategy is used. This configuration ensures that internal clients resolve services to the local LAN IP, while external traffic (if configured) uses the public IP.

1. Cloudflare (Public DNS)

Cloudflare manages the public zone for sterl.xyz. This is required for:

1. Let's Encrypt Wildcard Certificates: Traefik uses the CF_DNS_API_TOKEN to create temporary TXT records for validation.
2. External Access: If you open ports 80/443 on your router, these records direct traffic to your home.

Required Records

Type	Name	Content	Proxy Status
A	sterl.xyz	[Your Public IP]	Proxied (Orange Cloud) optional*
CNAME	*.sterl.xyz	sterl.xyz	Proxied (Orange Cloud) optional*

Note

: If Proxied is enabled, you benefit from Cloudflare's DDoS protection, but you will only see Cloudflare IPs in your logs unless TrustedProxies is configured in Traefik.

2. Pi-hole (Internal DNS)

For devices inside your home network (192.168.1.0/24), you must prevent them from going out to the internet just to come back in (NAT Loopback). Instead, Pi-hole should resolve these domains directly to the Docker Swarm Manager (Traefik).

The "A Record Shift"

Instead of defining every single service (grafana.sterl.xyz, plex.sterl.xyz, etc.), we use a Wildcard DNS Record in Pi-hole.

Configuration:

1. Login to Pi-hole.
2. Go to Local DNS > DNS Records.
3. Add the follow records:

Domain	IP Address	Description
sterl.xyz	192.168.1.196	Swarm Manager / Traefik Entrypoint
*.sterl.xyz	192.168.1.196	Wildcard Catch-all for all subdomains

Important

: 192.168.1.196 is your designated Traefik entry point (Manager Node). Ensure Traefik is running on this node or reachable via the Swarm Ingress Mesh on this IP.

Why this works

• External Request: whoami.sterl.xyz -> Cloudflare -> Public IP -> Router Port Forward (80/443) -> Traefik VIP.
• Internal Request: whoami.sterl.xyz -> Pi-hole -> 192.168.1.196 -> Traefik (Directly).

3. Verification

From a computer on your network, run:

nslookup whoami.sterl.xyz

Expected Result: 192.168.1.196 (The local LAN IP).

If you see a public IP, your Pi-hole configuration is not active or cached. Flush DNS keys (ipconfig /flushdns or sudo systemd-resolve --flush-caches).