Submit

Infrastructure guide

AdGuard Home Docker Compose: Durable DNS With a Rollback Path

Run AdGuard Home with persistent work and configuration directories, explicit DNS ownership, staged rollout, and fast router rollback.

Published and reviewed by OpenAlt · October 1, 2026

An IT professional operates a computer in a server room, managing network systems and connected devices.
Photo by panumas nikhomkhai on Pexels

The practical verdict is simple: an adguard home docker compose deployment suits a home lab when configuration is persisted, DNS ownership is explicit, and rollback remains possible. Docker simplifies packaging, but DNS is infrastructure: one port conflict or unreachable host can affect every client. Start with router access and a fallback resolver, then move one client at a time. The official project documents the image, separate work and conf persistence, resolver conflicts, capabilities, and releases. AdGuard Home’s Docker guidance is the reference point.

Table of Contents

Save router access and a fallback resolver before changing DNS

Save router access and a usable fallback resolver before changing any network-wide DNS setting. If the container, host, or network path fails, you must be able to restore the previous arrangement without depending on the new service.

  • Record the router’s management address and confirm normal client access.
  • Note current DNS and DHCP settings, plus the Docker host’s LAN address and assignment method.
  • Keep one resolver available for manual entry on a test client.
  • Choose the first test device before making changes.

Do not change router DNS and DHCP ownership in the same step. Staging the change shows whether a failure comes from name resolution, address assignment, or the container. Docker separates container networks from published host ports, so the fallback should include router access and a reachable client path. Docker networking documentation explains those boundaries.

Static address, port 53, local resolver and DHCP ownership

Give the Docker host a stable LAN address, make port 53 ownership explicit, and keep one DHCP authority during the first rollout.

  • Use a stable address or reservation so the router does not point to a moving target.
  • Reserve host port 53 for AdGuard Home and identify any local process already listening there.
  • Keep the router as DHCP owner initially so two services do not advertise conflicting DNS.
  • Restrict administrative access to your management path rather than exposing the control panel broadly.

The important conflict is whether another service answers DNS, binds port 53, or redirects clients elsewhere. Published ports and host networking behave differently, so choose deliberately. AdGuard Home Docker guidance and Docker networking cover the relevant concepts.

Minimal Compose with both work and conf persisted

Persist both AdGuard Home directories from the beginning so working data and configuration survive container replacement. This compact starting point exposes DNS and the initial web service:

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

Create both host directories before starting and keep them in a location covered by backups. The latest tag keeps the example simple, but it is not a rollback strategy; record a release identifier before making this service the household resolver. Official AdGuard Home repository documents the image, persistence, capabilities, and releases.

First-run wizard and one-client test before router rollout

Complete the first-run wizard through the mapped web port, then test exactly one client before changing the router. This isolates application configuration from network-wide impact.

  1. Start the container without changing router DNS.
  2. Open the mapped setup port from a trusted client.
  3. Complete the wizard and save the configuration.
  4. Point one client at the Docker host’s DNS address.
  5. Test ordinary resolution and a domain expected to be filtered.
  6. Return the client to its previous DNS if anything is unclear.

Write down the settings you chose. Confirm that the web interface is reachable from the management path and that the test client explicitly uses AdGuard Home. The wizard’s result is durable state, not disposable setup. AdGuard Home configuration documentation.

Detailed image of illuminated server racks showcasing modern technology infrastructure.
Photo by panumas nikhomkhai on Pexels
Close-up of a steel padlock on a mesh fence, symbolizing protection and security.
Photo by Connor Scott McManus on Pexels

Published ports versus host networking; private admin UI

Published ports with bridge networking are the safer starting point because they expose selected services while preserving Docker’s network boundary. Keep the admin interface private by binding it to a management address or applying access controls outside the container.

Publish only the ports clients need: DNS normally requires both UDP and TCP on port 53, while the first-run web service uses port 3000. Do not publish every optional service merely because the image supports it.

Host networking is an operational choice. It may simplify exposure, but it reduces separation and makes host-level conflicts more consequential. Docker Engine networking documents bridge and host networking, published ports, and isolation.

Validate filtering, attribution, upstream and failure behavior

Validate the complete DNS path, not just whether the web page loads. From the test client, confirm:

  • A normal domain resolves successfully.
  • A deliberately filtered request follows the configured policy.
  • The request is attributed to the expected client or group.
  • Upstream resolution succeeds when the filter does not block.
  • The client has a documented fallback when the service stops.
  • Router DNS changes do not create a competing path.

A passing browser test does not prove every device uses the service. Clients may cache answers, use encrypted DNS, or retain a manually configured resolver. Treat your client matrix and failure checks as the operating baseline. AdGuard Home repository describes the project’s capabilities and releases.

Back up both directories, pin, upgrade, rollback and recover

Back up both persisted directories, record the image version, and make rollback a deliberate file-and-container operation.

  • Copy the complete work directory.
  • Copy the complete conf directory.
  • Record the image tag or digest.
  • Save the Compose file and port decisions.
  • Note the router’s previous DNS settings.
  • Test that the backup can be read before upgrading.
  • Upgrade one version at a time when practical.
  • Keep the prior image reference until the new version is accepted.
  • Roll back the container and restore both directories together if needed.

Pinning makes the deployed image identifiable and gives rollback a concrete target. Keep the image reference and configuration record together so service state is recoverable as one unit. AdGuard Home releases and configuration settings provide the source references.

Troubleshoot reset wizard, conflicts, no traffic and loops

Troubleshoot by separating setup state, port ownership, client routing, and upstream behavior.

  • If the wizard reappears, inspect the persisted conf directory and confirm its mount.
  • If startup fails, identify the process using port 53 before changing Compose.
  • If there is no traffic, verify the test client’s active DNS settings.
  • If requests loop, check whether the local resolver or upstream points back to AdGuard Home.
  • If filtering works but attribution does not, check whether a resolver or gateway hides individual clients.
  • If the admin UI is unreachable, test its management path separately from DNS.

For broader planning, self-hosted guidance gives context for an adguard home self hosted deployment. One-click self-host options compare approaches, while the Pi-hole setup guide offers an adjacent DNS reference. The RTO/RPO impact calculator helps make downtime and data-loss assumptions explicit.

FAQ

Should AdGuard Home use host networking?

Host networking is optional, not mandatory. Published ports with bridge networking are a reasonable starting point because they expose selected services while preserving Docker’s boundary. Choose host networking only when simpler exposure is worth reduced separation and the host has no conflicting listeners. Docker networking.

Do both work and conf directories need backups?

Yes. Back up both persisted directories because work and conf are separate persistence concerns. Restore them together with the matching Compose file and image reference so rollback preserves a reproducible state. AdGuard Home Docker guidance.

When should the router point to AdGuard Home?

Change the router only after one client passes resolution, filtering, attribution, upstream, and failure checks. Keep the previous DNS values so you can reverse the change quickly.

What is the safest recovery if DNS stops working?

Restore the router’s previous DNS arrangement, return the test client to its fallback resolver, and inspect port ownership and persisted directories. If the image changed, use the recorded prior image reference and restore both directories together.