sterl/Homelab
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Add Pi-hole with AdGuard DOH/DOT integration, reorganize swarm stacks, add DNS/n8n docs

Browse Source
This commit is contained in:
sterlenjohnson
2025-12-18 15:38:57 +00:00
parent 827f8bbf9d
commit f0c525d0df
44 changed files with 3013 additions and 486 deletions
Download Patch File Download Diff File Expand all files Collapse all files

49
docs/guides/DNS_SETUP.md Normal file
View File

@@ -0,0 +1,49 @@
# 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:
```bash
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`).