NothingDNS
NothingDNS is a self-contained DNS server written in Go. It includes authoritative DNS, recursive forwarding/resolution, DNSSEC, encrypted transports, policy filtering, clustering, a REST management API, dnsctl, and an embedded React dashboard.
What is included
- DNS serving: UDP/TCP DNS, authoritative zones, forwarding, iterative resolution, DNS64, SVCB/HTTPS, IDNA, and QNAME minimization.
- Security and policy: DNSSEC validation/signing, DNS Cookies, DoH, DoT, DoQ, ODoH, DSO, ACLs, a recursion allow list (authoritative answers for everyone, recursion only for trusted networks), RRL, RPZ, and blocklists from hosts-style, URL, or plain domain-per-line sources.
- Operations: hot reload, Prometheus metrics, structured audit logs, memory protection, systemd/Docker/Kubernetes deployment assets, and backup/health-check scripts.
- Management: REST API with OpenAPI/Swagger,
dnsctl, and an embedded React 19 dashboard with WebSocket query streaming and zone management.
- Persistence and HA: built-in KV/WAL storage, AXFR/IXFR support, slave zones, split-horizon views, GeoIP responses, and gossip/Raft clustering.
Quick start
# Build the server and CLI with Go 1.26.9+
make build
# Run using the example configuration
go run ./cmd/nothingdns --config config.example.yaml
# Build the embedded web dashboard when frontend assets change
make build-web
# Run the short test suite
go test ./... -count=1 -short
Install scripts are available for packaged/binary-style setups:
# Linux/macOS
curl -fsSL https://raw.githubusercontent.com/NothingDNS/NothingDNS/main/install.sh | bash
# Windows PowerShell as Administrator
irm https://raw.githubusercontent.com/NothingDNS/NothingDNS/main/install.ps1 | iex
For Docker and Kubernetes examples, see QUICK_START.md and docs/OPERATIONS.md.
Docker / GHCR: The container image is published to
ghcr.io/nothingdns/nothingdns:latest. The package is currently private —
to pull it, authenticate with a GitHub PAT that has read:packages scope:
echo "$GITHUB_TOKEN" | docker login ghcr.io -u USERNAME --password-stdin
(see docs/DEPLOYMENT_CHECKLIST.md for details).
Repository map
| Path | Purpose |
|---|
cmd/nothingdns/ | Server entry point and runtime wiring |
cmd/dnsctl/ | Management CLI |
internal/ | DNS protocol, resolver, API, DNSSEC, storage, clustering, transports, and support packages |
web/ | React dashboard source and build tooling |
internal/dashboard/static/dist/ | Embedded dashboard build output served by the Go binary |
deploy/ | systemd, Docker/Kubernetes, and Helm deployment assets |
docs/ | Architecture, configuration, operations, API, CLI, testing, performance, and release documentation |
examples/ | Example-oriented documentation |
scripts/ | Development, smoke-test, backup, and health-check helpers |
Generated runtime state and local build artifacts such as nothingdns, dnsctl, bin/, logs/, zones/, clusters/, *.db, and cache.json are intentionally ignored.
Documentation
Start with the documentation index. Common entry points:
Development
make build # server + dnsctl
make build-web # dashboard bundle
make test # short Go tests
make test-full # full Go tests
make lint # go vet + gofmt check
make clean # remove local binaries and coverage files
The web package uses npm scripts:
cd web
npm install
npm run build
npm test # unit tests with Vitest + React Testing Library
npm run lint
Configuration
Use config.example.yaml as the source-aligned example configuration. The full schema and hot-reload behavior are documented in docs/CONFIG_REFERENCE.md.
Contributing and license
Contributions are welcome; see CONTRIBUTING.md. NothingDNS is released under the MIT License.
