Getting Started
Quick Start
Get DNS Resolver running in minutes with a minimal Docker Compose setup.
Quick Start
This guide walks you through the minimal setup to serve your internal domain and auto-resolve running containers.
Step 1 — Create the environment file
git clone https://github.com/circle-rd/dns-resolver.git
cd dns-resolver
cp .env.example .env
$EDITOR .env
Set the two required variables:
# Your internal domain zone
DOMAIN=home.example.com
# The IP of the host running the container
# All *.home.example.com queries will resolve to this IP.
HOST_IP=192.168.1.10
The remaining variables have sensible defaults — you only need to change them for advanced configurations. See Environment Variables.
Step 2 — Start the container
docker compose up -d
The container prints a startup summary:
=== DNS Resolver (CoreDNS + docker-gen) ===
Domain : home.example.com
Host IP : 192.168.1.10
Upstream DNS : 1.1.1.1
Authoritative: true
ACME DNS-01 : false
Hosts reload : 15s (CoreDNS re-reads /etc/coredns/hosts)
Zone reload : 30s (CoreDNS re-reads the zone file)
docker-gen : wait 5s:30s (min:max debounce)
Step 3 — Point your client to the resolver
On your router or client device, set the DNS server to HOST_IP.
Alternatively, in your Traefik or other container stack, specify:
dns:
- 192.168.1.10
or use Docker's built-in DNS override:
# docker-compose.yml for your services
services:
my-service:
dns:
- 192.168.1.10
Step 4 — Verify DNS resolution
# Wildcard zone — all subdomains resolve to HOST_IP
dig @192.168.1.10 anything.home.example.com A +short
# → 192.168.1.10
# Root domain
dig @192.168.1.10 home.example.com A +short
# → 192.168.1.10
# External query — forwarded to DNS_UPSTREAM
dig @192.168.1.10 github.com A +short
# → <GitHub's IP>
After starting another container, its hostname should appear within HOSTS_RELOAD seconds (default 15 s):
dig @192.168.1.10 my-container-name A +short
# → <container's internal IP>
docker-compose ports mapping
ports:
- "${HOST_IP}:53:53/udp"
- "${HOST_IP}:53:53/tcp"
Binding to ${HOST_IP} (not 0.0.0.0) avoids conflicts with systemd-resolved on standard Linux hosts.
Next steps
- Environment Variables — full reference
- Traefik integration — pair DNS Resolver with Traefik for zero-config service routing
- ACME DNS-01 — internal certificate issuance without exposing port 80