Submit

Infrastructure guide

Pi-hole Setup: Reliable DNS Blocking Without Breaking the Network

Deploy Pi-hole with a stable address, deliberate DNS and DHCP ownership, durable configuration, staged rollout, and a tested rollback path.

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

For a home lab or small office, Pi-hole is a practical DNS-blocking choice when you control addressing, router settings, and rollback. Docker adds container management; bare metal removes a runtime layer but still demands network discipline. Choose the simpler path you can restore confidently, then change DNS for one client before the whole network. (Pi-hole prerequisites)

Table of Contents

Decision first: Docker or bare metal, and who owns DHCP

Choose Docker if you already operate containers and want Pi-hole separated from the host. Choose bare metal if a dedicated host with fewer runtime layers is easier to recover. Before deployment, decide whether the router or Pi-hole owns DHCP. The correct choice has one clear network authority and a documented rollback. (Pi-hole main documentation)

  • Use Docker for a familiar pi hole docker compose workflow.
  • Use bare metal when the host is dedicated and simpler to recover.
  • Keep DHCP on the router unless you have a specific reason to move it.
  • If Pi-hole owns DHCP, document how clients receive an address when Pi-hole is unavailable.

Treat this as an operations decision, not an installation-style preference.

Preflight: static address, port 53 conflicts, router access, written rollback

Before installing, give the Pi-hole host a stable address, confirm that TCP and UDP port 53 are available, verify router administration access, and write down the current DNS settings. (Raspberry Pi Pi-hole tutorial)

CheckPass conditionRecovery note
Static addressThe host address will not change unexpectedlyRecord the prior address and DHCP reservation
Port 53TCP and UDP 53 are availableIdentify the existing listener
Router accessYou can edit DNS or DHCP settingsKeep the router login path available
RollbackPrior DNS values are recordedRestore client or router settings first

Also record the address you will advertise, whether the router distributes DNS through DHCP, which device provides DHCP, the client setting to restore, and a second way to reach the router if DNS stops working.

The prerequisites specify 512 MB of RAM, 2 GB of free space minimum, and 4 GB recommended, plus a supported-operating-system list. Validate them against the chosen host. (Pi-hole prerequisites)

Current official Compose shape with durable paths and no published secrets

The official Docker approach requires DNS on both TCP and UDP port 53 and persistent storage for /etc/pihole. Keep current FTLCONF_* settings in a private environment file, never publish credentials in a shared Compose file, and adapt this structural shape to your release. (Pi-hole Docker documentation)

services:
  pihole:
    image: pihole/pihole:latest
    container_name: pihole
    ports:
      - "53:53/tcp"
      - "53:53/udp"
    volumes:
      - ./etc-pihole:/etc/pihole
    env_file:
      - .env
    restart: unless-stopped

Keep ./etc-pihole on durable storage covered by backups and keep .env private and out of public repositories. Include only the current FTLCONF_* variables required by your release. Pin a tested image version before changes affecting a busy network, and never expose the administration interface to the public internet. Both DNS protocols are mapped, persistent data survives container replacement, and secrets remain separate from the published service definition.

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

Test one client before changing the whole network

Change one client first, point it to the Pi-hole host’s stable address, and confirm ordinary resolution and intended blocking. If DNS fails, restore its former setting immediately. Do not change router-wide DNS until one controlled client works through normal browsing and direct queries. (Pi-hole main documentation)

  1. Record the client’s existing DNS settings.
  2. Set only that client’s DNS server to Pi-hole.
  3. Renew its lease or reconnect it.
  4. Browse to several ordinary sites.
  5. Run a direct query with dig or nslookup.
  6. Confirm the administration path remains reachable.
  7. Restore the old setting if any step fails.

This isolates Pi-hole from the router and provides a known-good client for later verification.

Router-wide rollout, DNS fallback/bypass, and useful verification

After one client works, distribute Pi-hole through the router’s DNS or DHCP settings and renew leases gradually. Avoid a public resolver as a casual fallback when blocking matters: clients may bypass Pi-hole. Verify the assigned DNS address and keep client-level rollback available. (Raspberry Pi Pi-hole tutorial)

  1. Change the router setting during a quiet maintenance window.
  2. Renew one additional client and inspect its assigned DNS server.
  3. Check ordinary browsing and intentional blocking.
  4. Renew remaining clients in small groups.
  5. Check wired, wireless, guest, and other network segments separately.
  6. Record devices using manually configured DNS.

Verify that clients receive the Pi-hole address, ordinary domains resolve, the administration interface remains reachable, queries arrive from expected clients, and a deliberately selected blocked domain behaves as intended. Correct or document any manual-DNS bypasses. If the router lacks the needed control, limit Pi-hole to selected clients instead of forcing a fragile network-wide configuration.

Back up /etc/pihole, upgrade deliberately, rehearse rollback

Back up persistent /etc/pihole data before upgrades and preserve the previous working configuration. Change one component at a time, verify one client, and rehearse restoring the former DNS path. The goal is a recoverable service change with a known failure boundary. (Pi-hole Docker documentation)

For Docker, back up the host directory mapped to /etc/pihole; preserve the Compose file and private environment file; record the previous image version; and test a single client before renewing the wider network. If DNS fails, restore the former image or configuration and revert client or router DNS. Keep restore instructions with the backup.

Troubleshoot no DNS, no blocking, and admin-only access

Troubleshoot from the network edge inward: determine whether clients reach DNS, whether Pi-hole receives queries, and whether blocking is configured as intended. If only administration works, treat web access and DNS as separate paths and restore client DNS while investigating. (Pi-hole main documentation)

No DNS resolution

Check the advertised address, port 53 availability, and whether the container or host is running. Test the Pi-hole address directly from one client. If the direct query fails, restore the former DNS setting while inspecting the service and router configuration.

DNS works but blocking does not

Confirm the client is actually using Pi-hole rather than a manual or fallback resolver. Check the query path and blocking configuration, then retest with one intentionally selected domain. Change one setting at a time so the cause remains visible.

Administration works but clients fail

Verify TCP and UDP 53, confirm the client’s assigned DNS address, and test from another client. Once stable, connect the wider self-hosting decision to OpenAlt’s self-hosted guide, one-click self-host options, or the AdGuard Home Docker Compose comparison. For outage planning, use the RTO/RPO impact calculator.

FAQ

These answers follow the same conservative pattern: make one controlled change, preserve durable configuration, and maintain a rollback that does not depend on DNS being healthy.

Should I run Pi-hole in Docker or on bare metal?

Choose Docker when container operations are familiar and durable storage is easy to manage. Choose bare metal when a dedicated host is simpler to recover. Both are supported paths; operational familiarity and recovery confidence matter more than a universally preferred format.

How much hardware does Pi-hole need?

The supplied prerequisites specify 512 MB of RAM and 2 GB of free space minimum, with 4 GB recommended. Check the supported operating-system list before deployment, and leave additional room for the host, logs, backups, and other services sharing the machine.

Should I configure a second public DNS server?

Avoid a public fallback when network-wide blocking is an enforcement requirement because clients may use it as a bypass. If availability matters more than strict filtering, document the tradeoff and test the behavior deliberately. A fallback does not preserve the same policy automatically.

What is the safest rollback?

Restore the client’s prior DNS setting first, then restore router DNS or DHCP settings if required. Keep the stable host address, /etc/pihole backup, previous Compose configuration, and written router access instructions together.