---
title: "Connection: Docker DNS + AdGuard Split-Horizon — The Missing Link"
description: "Docker containers inside LXC always need explicit AdGuard DNS to resolve homelab internal domains — without it, split-horizon DNS is invisible to services"
connects:
  - "concepts/docker-lxc-dns-configuration"
  - "concepts/adguard-dns-rewrites-homelab"
sources:
  - "daily/2026-04-28.md"
created: 2026-04-28
updated: 2026-04-28
---

# Connection: Docker DNS + AdGuard Split-Horizon — The Missing Link

## The Connection

AdGuard Home provides split-horizon DNS for internal homelab services (`*.ai-impress.com → internal IP`). Docker containers running in LXC/Proxmox use router DNS by default — not AdGuard. This means Docker services (Homarr, Uptime Kuma, monitoring agents) cannot resolve internal domains even though the LXC host itself can. AdGuard's DNS rewrites are invisible to Docker unless explicitly configured.

## Key Insight

**Two correct things break when combined.** AdGuard DNS rewrites work correctly at the OS level. Docker DNS inheritance works correctly by design. But "inherit from LXC host" means "inherit router DNS" (what DHCP assigned), not "inherit whatever the human added to `/etc/resolv.conf`." The result: every Docker service that health-checks a homelab service by domain name silently fails.

The symptom is deceptive: the Homarr UI shows the service as "offline" when it's actually online — Homarr's health ping resolves `jellyfin.ai-impress.com` to nothing, not to the wrong IP. The service is fine; the container's DNS is wrong.

## Where This Pattern Bites

| Service | Use of internal DNS | Failure symptom |
|---------|---------------------|-----------------|
| Homarr | Ping checks for dashboard tiles | Tiles show red/offline |
| Homepage | Widget API calls | Widget API errors |
| Uptime Kuma | Monitor HTTP checks | False-negative alerts |
| Beszel agent | Connecting to hub by hostname | Agent can't register |
| Any monitoring container | Checking sibling services by domain | False alerts across board |

## The Fix (Always)

In every `docker-compose.yml` for Docker services that reference homelab domains:

```yaml
services:
  your-service:
    dns:
      - 192.168.1.225   # AdGuard Home — resolves *.ai-impress.com
      - 1.1.1.1         # Cloudflare — fallback for public DNS
```

Or globally for all containers on an LXC:

```json
// /etc/docker/daemon.json on the LXC
{
  "dns": ["192.168.1.225", "1.1.1.1"]
}
```

## Why This Isn't Obvious

AdGuard is configured in the router's DHCP settings (or the Tailscale admin panel) as the primary DNS for all LAN devices. LAN devices — including the LXC host — do use AdGuard. But Docker adds its own DNS resolution layer, bypassing the LXC's `/etc/resolv.conf` for containers and using whatever Docker daemon DNS is configured (default: inherit from host, which means the router).

The key confusion: "the LXC uses AdGuard" ≠ "containers in the LXC use AdGuard." These are two different DNS stacks.

## Connection to AdGuard DNS Rewrites

AdGuard's wildcard rewrite `*.ai-impress.com → NPM IP` is the foundation of the homelab's internal domain system. Everything that wants to reach a homelab service by friendly domain depends on this rewrite. For Docker services, the chain is:

```
Docker service queries *.ai-impress.com
    ↓ resolves via AdGuard (192.168.1.225)
    ↓ AdGuard returns NPM IP (192.168.1.205)
    ↓ NPM routes to the actual service container
Docker service connects to the right container
```

If any link in this chain is missing — Docker not using AdGuard — the entire chain fails silently at DNS resolution.

## Related

- [[wiki/concepts/docker-lxc-dns-configuration]] — implementation details, daemon.json config, diagnosing DNS inside containers
- [[wiki/concepts/adguard-dns-rewrites-homelab]] — the wildcard DNS rewrite that this connection depends on
- [[wiki/concepts/homarr-sqlite-integration-cleanup]] — the session where this was discovered (Homarr ping checks failing)
- [[wiki/concepts/lxc-arp-cache-api-failures]] — a different LXC networking failure that causes similar "service unreachable" symptoms
