digitaldriveio/dns-healthcheck repository overview

⁠dns-healthcheck (Docker Hub README)

Lightweight DNS probe container that reports resolver readiness through Docker healthchecks. Point it at AdGuard Home, Unbound, or any resolver to delay dependent services until valid DNS answers are available.

⁠How It Works

• Base image alpine:3.20 + bind-tools
• Script /usr/local/bin/check_dns.sh runs every second via Docker healthcheck
• Performs dig +time=1 +tries=1 <DOMAIN> @<DNS_SERVER>
• Fails on non-zero dig exit, SERVFAIL, REFUSED, or missing ANSWER SECTION
• After the first success, throttles to one real DNS query per minute, while failures revert to 1s retries
• Container otherwise sleeps indefinitely; only health state matters
• Multi-arch image covering linux/amd64 and linux/arm64

⁠Configuration

Set both variables to match your infrastructure. Any failure keeps the container in unhealthy.

⁠Usage

docker run \
  --name dns-health \
  -e DOMAIN_TO_CHECK=example.org \
  -e DNS_SERVER=adguard \
  digitaldriveio/dns-healthcheck:snapshot

Check status:

docker inspect --format '{{json .State.Health}}' dns-health

⁠Compose snippet

depends_on:
  dns-health:
    condition: service_healthy

⁠Notes

• Best suited for orchestrations where DNS readiness gates other services.
• NXDOMAIN and empty answers are considered failures on purpose.