An authoritative DNS server that continuously health-checks backend IPs via TCP and automatically removes unhealthy endpoints from DNS responses — no external orchestration required.
docker run -d \
--name a-healthy-dns \
-p 53053:53053/udp \
-e DNS_HOSTED_ZONE="example.com" \
-e DNS_ZONE_RESOLUTIONS='{"www":{"ips":["192.168.1.100","192.168.1.101"],"health_port":8080}}' \
-e DNS_NAME_SERVERS='["ns1.example.com"]' \
-e DNS_PORT="53053" \
indisoluble/a-healthy-dnsVerify it is running:
dig @localhost -p 53053 www.example.com
docker logs a-healthy-dnsgit clone https://github.com/indisoluble/a-healthy-dns.git
cd a-healthy-dns
pip install .
a-healthy-dns \
--hosted-zone example.com \
--zone-resolutions '{"www":{"ips":["192.168.1.100","192.168.1.101"],"health_port":8080}}' \
--ns '["ns1.example.com"]'Requires Python 3.10+.
- Health checks run in the background, testing TCP connectivity to each
(ip, health_port)pair at a configurable interval. - When an IP becomes unhealthy it is removed from DNS A record responses immediately on the next zone update.
- When all IPs for a subdomain are unhealthy, the subdomain returns
NXDOMAIN. - Multiple domain aliases can share the same health-checked records without duplicated checks (
--alias-zones). - DNSSEC zone signing is supported when a private key is provided (
--priv-key-path).
| Document | Contents |
|---|---|
| docs/docker.md | Docker deployment: image details, Compose, deployment patterns, container management, security, and orchestration |
| docs/configuration-reference.md | All CLI flags and Docker env vars with defaults and examples |
| docs/troubleshooting.md | Common issues, debugging, and operational procedures |
| docs/project-brief.md | Goals, non-goals, constraints, requirements |
| docs/system-patterns.md | Architecture and design patterns |
| docs/project-rules.md | Toolchain, QA commands, CI/CD workflow, naming conventions |
| docs/table-of-contents.md | Full documentation index |