Show HN: Lightweight DNS server for Docker containers

4 hours ago 1

Wakemae is a lightweight DNS server for Docker containers. Simply add labels to your containers to automatically access them by domain name. This project is similar dnsdock.

Automatic DNS Registration: Monitors Docker container start/stop events and automatically manages DNS records
Label-based Configuration: Uses wakemae.domain labels to set domain names
Real-time Updates: Monitors and reflects container state changes in real-time
Fallback Support: Forwards unregistered domains to upstream DNS servers
A/CNAME Record Support: Supports both A records and CNAME records

Wakemae supports configuration via a config.yml file. If no configuration file is found, default settings will be used.

config.yml should locate under /etc/wakemae/.

Create a config.yml file in the same directory as the wakemae binary:

dns: bind_address: "127.0.0.1:53" upstream: "1.1.1.1:53" timeout: "5s"

Option Description Default Value

dns.bind_address	DNS server bind address and port	127.0.0.1:53
dns.upstream	Upstream DNS server for fallback queries	1.1.1.1:53
dns.timeout	DNS query timeout	5s

If config.yml is not found, wakemae will use the default configuration shown above.

Docker Compose Example (reccomend)

Sample configuration is available in example/docker-compose.yml:

services: wakemae: image: ghcr.io/ei-sugimoto/wakemae:latest volumes: - /var/run/docker.sock:/var/run/docker.sock networks: wakemae_network: ipv4_address: 172.20.0.10 web1: image: nginx:latest ports: - 8080:80 labels: wakemae.domain: web1.docker dns: - 172.20.0.10 networks: wakemae_network: ipv4_address: 172.20.0.11 depends_on: - wakemae networks: wakemae_network: driver: bridge ipam: config: - subnet: 172.20.0.0/16

With this configuration, you can access the nginx container via web1.docker.

docker compose exec web1 bash -c "apt install curl && curl http://web2.docker/"

Wakemae consists of the following components:

DNS Server: Handles DNS queries on both UDP and TCP
Docker Listener: Monitors Docker events to detect container start/stop
Registry: Manages domain name to IP address mappings

When a Docker container starts, the Docker Listener detects the event
Checks the container's wakemae.domain label
If the label exists, registers the IP address and domain name mapping in the Registry
When DNS queries arrive, references the Registry to return IP addresses
When containers stop, removes the corresponding records

Start the DNS server and Docker monitoring.

Configuration can be customized via the config.yml file. See the Configuration section for details.

This project is released under the MIT License. See the LICENSE file for details.

Pull requests and issue reports are welcome. Please check existing issues before contributing.