Self-Hosting DNS with Pi-hole or AdGuard Home: Local Records, DoH, and Failover

Overview

DNS translates names such as nas.example.home or grafana.lan into IP addresses. On a home network, relying entirely on a router or public resolver makes local services harder to name consistently. A self-hosted DNS server lets you create local records, apply network-wide filtering, and inspect which domains clients request.

Pi-hole and AdGuard Home are both practical choices for a self hosted DNS server. Pi-hole has a long-standing community and a focused blocking workflow. AdGuard Home presents more features in one interface, including broader per-client settings and convenient encrypted-upstream configuration. Neither replaces a firewall, endpoint security, or backups, and DNS filtering should not be treated as a complete privacy system.

For a small homelab, run one instance first and make it stable before adding redundancy. Keep the DNS container on a fixed LAN address, reserve that address in your router or assign it carefully at the host level, and avoid exposing port 53 to the public internet. If you publish web applications externally, use a reverse proxy or a controlled tunnel instead; see the Cloudflare Tunnel self-hosting guide for one approach.

What to track

Local records and split DNS

Create names for services instead of memorizing addresses: files.home.arpa, vault.home.arpa, or monitor.home.arpa. The reserved home.arpa namespace is intended for home networks. Use one internal naming scheme and document each record, destination address, owner, and purpose.

Split DNS means the same public hostname can resolve differently inside and outside your network. For example, photos.example.com can resolve to a private reverse-proxy address on the LAN while public DNS points visitors to your external endpoint. This avoids unnecessary hairpin routing and keeps internal traffic local. Only use split DNS when you can maintain both views consistently.

Upstream resolvers and DoH

Your local resolver can forward unanswered queries to an upstream provider. Compare the available options by policy, reliability, latency from your network, and whether you need DNS-over-HTTPS (DoH) or DNS-over-TLS. Encrypted transport protects the connection between your resolver and its upstream, but it does not make local DNS requests invisible to the resolver itself.

Configure at least one primary upstream and, where practical, a second independent option. Do not add a long list simply to appear redundant: different providers may return different answers or handle filtering differently. Record the chosen endpoints and test them after software upgrades.

DHCP, clients, and filtering

The simplest arrangement is to leave DHCP on your router and advertise the DNS server's LAN address to clients. Some routers accept only one DNS address; others advertise multiple addresses. If your router cannot reliably distribute the desired DNS settings, Pi-hole or AdGuard Home can provide DHCP, but only one device should manage DHCP on the network.

Track blocked-domain volume, frequently blocked domains, client-specific failures, and queries that bypass your resolver. Smart TVs, VPN clients, guest networks, and devices with hard-coded DNS settings can behave differently. An allowlist entry should identify the application that needs it and include a reason, rather than becoming a permanent reaction to a broken page.

Docker deployment basics

For either application, persist its configuration and data directories, set a timezone, and publish DNS ports only on the LAN interface when your Docker setup allows it. A simplified AdGuard Home Compose pattern looks like this:

services:
  adguard:
    image: adguard/adguardhome:latest
    container_name: adguard
    restart: unless-stopped
    volumes:
      - ./work:/opt/adguardhome/work
      - ./conf:/opt/adguardhome/conf
    ports:
      - "192.168.1.10:53:53/tcp"
      - "192.168.1.10:53:53/udp"
      - "3000:3000/tcp"

Replace the address and paths with values appropriate to your host. Pinning a reviewed image version instead of automatically taking every latest image can make upgrades easier to stage. Pi-hole uses a similar pattern with persistent volumes and DNS port mappings, but its required environment variables and supported features vary by release, so use the current project documentation when creating the Compose file.

Cadence and checkpoints

Use a short weekly check during the first month, then move to a monthly review once the service is predictable. A useful checkpoint includes:

• Confirm that the DNS service, container, and host are running.
• Resolve several local records from a wired client and a wireless client.
• Check that DHCP is advertising the intended resolver.
• Review blocked-query logs for false positives and repeated client errors.
• Test each configured upstream and confirm that failed upstreams do not leave clients waiting indefinitely.
• Review available application updates and read release notes before applying them.
• Back up configuration, custom rules, local records, and any DHCP settings.

Every quarter, test the recovery path on a separate host or a clean container. A DNS backup that cannot be restored is only a record of what used to work. If DNS is important to your home server setup, monitor its web endpoint and run a DNS query check from another device. You can combine that with a wider stack described in the self-hosted monitoring guide.

How to interpret changes

A sudden increase in blocked queries is not automatically a problem. It may reflect a newly installed application, a firmware update, or a device repeatedly retrying a request. First identify the client and domain, then determine whether the request is expected. If an application breaks, temporarily allow the narrowest domain that restores the required function and observe it before making the exception permanent.

When local names fail but public names work, inspect local records, the client DNS server, and the authoritative address for the service. When all names fail, test the resolver directly from a client with a command such as nslookup example.com 192.168.1.10. A successful direct query combined with failed normal browsing usually points to DHCP, client caching, VPN software, or a browser-specific secure-DNS setting.

When answers are slow or inconsistent, compare the local resolver with each upstream, inspect resource usage on the host, and check for duplicate DHCP servers. Do not solve intermittent failures by adding random DNS addresses to clients; that can bypass filtering and make diagnosis harder.

Troubleshooting decision tree

1. No device can resolve names: verify the container or service, port 53 bindings, host firewall, and upstream connectivity.
2. Only one device fails: inspect its DHCP lease, manually configured DNS, VPN, browser DoH setting, and local cache.
3. Local names fail but internet names work: review the local record or rewrite, suffix expectations, and the address of the target service.
4. One application fails: inspect blocked queries, allow only the required domain, and check whether the application uses its own resolver.
5. Failures occur during restarts: add a second resolver, keep its configuration separate, and verify that clients can reach it.

When to revisit

Revisit this setup after major Pi-hole or AdGuard Home releases, changes to your router or DHCP configuration, migration to a new Docker host, or the addition of a reverse proxy and several new self-hosted apps. Also review it when you introduce a guest VLAN, VPN, IPv6, a new public domain, or a second internet connection. These changes can alter which resolver clients use and whether local records remain reachable.

For a practical migration, export or record local records, allowlists, blocklists, upstream settings, DHCP leases, and administrator access details. Lower complexity before switching: remove stale entries and keep a short list of intentionally chosen blocklists. Install the replacement on a different address, test it from representative clients, then change DHCP only after direct queries succeed. Keep the old resolver available during the transition, but avoid advertising both systems indefinitely unless you have designed them as a deliberate redundant pair.

Finish each review by writing down three facts: which address clients should use, where the configuration backup is stored, and how to restore service if the primary host fails. For broader operational routines, pair this DNS checklist with the self-hosted server maintenance checklist and the Docker backup strategy. Reliable local DNS is less about choosing a perfect product than maintaining clear records, controlled changes, and a tested fallback.