dns-proxy-server (DPS) is a lightweight DNS server for developers and server administrators who need hostnames to resolve differently depending on Docker containers, local configuration, or the internet.

What it is

dns-proxy-server, commonly shortened to DPS, is a Java DNS server tool aimed at end users — developers and server administrators — working in environments where one hostname must resolve to different IPs depending on the configured environment. It resolves hostnames from Docker containers, from a local configuration database, and recursively from a list of configured remote DNS servers, and it ships with a graphic interface for managing records.

The concrete problem it solves is service discovery in containerized development: rather than editing system resolver files or hardcoding IPs when a container starts or changes address, DPS looks up container names and hostnames automatically and falls back to local records and then to the internet. It lives in the Docker and networking ecosystem, serving as an authoritative and recursive DNS server (RFC-1035 compliant) that replaces manual /etc/hosts editing and static host file configuration for container workflows.

Key capabilities

• Resolves hostnames to Docker containers, either from the container name (e.g. nginx-app.docker) or from a hostname set at docker run (e.g. nginx.dev), via the --register-container-names flag
• Resolves pre-configured entries stored in conf/config.json, alongside recursive resolution from a configured list of remote DNS servers
• Supports wildcard and regex hostname resolution, including resolving all subdomains of a container hostname to that container (e.g. .nginx.dev)
• Provides a graphic interface to Create/List/Update/Delete A, AAAA, and CNAME records
• Resolves the host machine IP through the special host.docker hostname, and stub hostnames such as machine-1.192.168.0.1.stub resolving to 192.168.0.1
• Runs as an authoritative server, a recursive server, and in secondary mode, with caching, IPv6, and DNS over HTTPS support
• Is RFC-1035 compliant

Who uses it and how

• Developers running multiple Docker containers on a single host who want container names and custom hostnames resolvable without editing host resolver files
• Server administrators operating a local DNS endpoint on a chosen port (e.g. sudo ./dns-proxy-server --server-port 5555 --register-container-names) and pointing clients at it with nslookup
• Teams where the same hostname must map to different IPs per environment, using conf/config.json entries to switch resolution targets
• Users on Mac, Windows, or Docker who need consistent name resolution across platforms, following the project's platform-specific running documentation
• Operators who want local records plus internet fallback through one service, resolving internal entries first and passing everything else to remote DNS servers

Getting started

Download the latest native binary from the releases page and run it directly (e.g. sudo ./dns-proxy-server --server-port 5555 --register-container-names), or run the Docker Hub image defreitas/dns-proxy-server.

How it compares

The facts name no paid products this project replaces and no other specific tools in the same registry, so dns-proxy-server stands alone in this registry. Its stated comparison axes are functional: it is both authoritative and recursive, secondary-capable, caching-enabled, IPv6-capable, wildcard-capable, DNS-over-HTTPS capable, and RFC-1035 compliant.

When to use it — and when not

You should pick it when you are already running containers and want hostname resolution driven by container metadata plus a local record database, accepting that you are operating a DNS service on your own host and managing conf/config.json records yourself. It is a poorer fit if you do not use Docker or do not want to run and maintain a DNS endpoint, and prospective users should note the README itself directs readers to a full external documentation site rather than detailing behavior inline, so budget time for reading those docs before committing to it.

sudo ./dns-proxy-server --server-port 5555 --register-container-names

$ docker run --rm --name nginx-app nginx

$ nslookup -po=5555 nginx-app.docker 127.0.0.1
172.17.0.3

$ docker run --rm --hostname nginx.dev nginx

$ nslookup -po=5555 nginx.dev 127.0.0.1
172.17.0.3

$ nslookup -po=5555 dps-sample.dev 127.0.0.1
192.168.0.254

$ nslookup -po=5555 google.com 127.0.0.1
142.250.79.174

$ nslookup -po=5555 machine-1.192.168.0.1.stub 127.0.0.1
192.168.0.1

$ nslookup -po=5555 host.docker 127.0.0.1
172.22.230.67

$ docker run --rm --hostname .nginx.dev nginx

$ nslookup -po=5555 site1.nginx.dev 127.0.0.1
172.17.0.3