{"id":15527459,"url":"https://github.com/medunes/docker-dns","last_synced_at":"2026-04-12T02:09:40.017Z","repository":{"id":269767550,"uuid":"893441202","full_name":"MedUnes/docker-dns","owner":"MedUnes","description":"A lightweight DNS server, written in Go, that resolves Docker container names to their IP addresses, enabling seamless networking between containers and the host.","archived":false,"fork":false,"pushed_at":"2025-08-21T16:19:04.000Z","size":1909,"stargazers_count":2,"open_issues_count":0,"forks_count":0,"subscribers_count":2,"default_branch":"master","last_synced_at":"2026-03-07T16:11:22.783Z","etag":null,"topics":["debian","dns","docker","docker-compose","docker-container","go","golang","linux","network","networking","nginx","reverse-proxy"],"latest_commit_sha":null,"homepage":"https://medunes.github.io/docker-dns/","language":"Go","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"agpl-3.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/MedUnes.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2024-11-24T13:10:27.000Z","updated_at":"2025-11-24T02:38:18.000Z","dependencies_parsed_at":"2026-03-07T11:14:14.666Z","dependency_job_id":null,"html_url":"https://github.com/MedUnes/docker-dns","commit_stats":null,"previous_names":["medunes/docker-dns"],"tags_count":107,"template":false,"template_full_name":null,"purl":"pkg:github/MedUnes/docker-dns","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/MedUnes%2Fdocker-dns","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/MedUnes%2Fdocker-dns/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/MedUnes%2Fdocker-dns/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/MedUnes%2Fdocker-dns/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/MedUnes","download_url":"https://codeload.github.com/MedUnes/docker-dns/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/MedUnes%2Fdocker-dns/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":31701642,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-04-11T21:17:31.016Z","status":"online","status_checked_at":"2026-04-12T02:00:06.763Z","response_time":58,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["debian","dns","docker","docker-compose","docker-container","go","golang","linux","network","networking","nginx","reverse-proxy"],"created_at":"2024-10-02T11:06:27.195Z","updated_at":"2026-04-12T02:09:40.012Z","avatar_url":"https://github.com/MedUnes.png","language":"Go","funding_links":[],"categories":[],"sub_categories":[],"readme":"\u003ch1 align=\"center\"\u003e\nDocker DNS\n    \u003cbr\u003e\n    \u003cimg src=\"./logo.png\" width=\"200\" alt=\"\"\u003e\n\u003c/h1\u003e\n\n[![Tests](https://github.com/MedUnes/docker-dns/actions/workflows/test.yml/badge.svg)](https://github.com/MedUnes/docker-dns/actions/workflows/test.yml) [![Release](https://github.com/MedUnes/docker-dns/actions/workflows/release.yml/badge.svg)](https://github.com/MedUnes/docker-dns/actions/workflows/release.yml) [![Go Report Card](https://goreportcard.com/badge/github.com/medunes/docker-dns)](https://goreportcard.com/report/github.com/medunes/docker-dns) [![License](https://img.shields.io/github/license/medunes/docker-dns)](LICENSE) [![Go Reference](https://pkg.go.dev/badge/github.com/medunes/docker-dns.svg)](https://pkg.go.dev/github.com/medunes/docker-dns)\n\nA lightweight DNS server that resolves Docker container names to their IP addresses, enabling seamless networking\nbetween containers and the host.\n\n## Features\n\n- **Automatic DNS Resolution**: Resolve Docker container names with a custom TLD to their respective IP addresses.\n- **Caching Mechanism**: Configurable TTL for DNS cache entries to improve performance.\n- **Simple Configuration**: Minimal setup with command-line options or a configuration file.\n- **Debian Package**: Easy-to-install `.deb` package for seamless integration.\n- **Fallback DNS**: Forwards non-Docker queries to configurable DNS servers.\n- **Lightweight and Fast**: Built with Go for high performance.\n\n## Architecture\n\nThe diagram below shows how a DNS query flows through the system, from the network listeners down to Docker or upstream\nresolvers.\n![Architecture](./architecture.png)\n\nQueries for managed TLDs (like `.docker` or `.local`) are resolved by inspecting the matching Docker container. A\nsingleflight gate prevents concurrent cache misses for the same name from hammering the Docker API. All other queries\nare forwarded in parallel to the configured upstream resolvers, returning the first successful response.\n\n## Installation for Linux/Debian:\n\n**Important**: Please read [this documentation](./docs/Systemd.md) carefully to have a deep overview on how systemd\nintegrates with DNS resolution for each ditro/version..\n\n### Download and Install the Debian Package\n\n1. **Download the `.deb` Package**:\n    - Go to the [Releases](https://github.com/MedUnes/docker-dns/releases) page.\n    - Find the release matching your desired version (e.g., `v1.0.2`).\n    - Download the `.deb` file:\n      ```\n      wget https://github.com/MedUnes/docker-dns/releases/download/v1.0.2/docker-dns-1.0.2_amd64.deb\n      ```\n\n2. **Install the Package**:\n   ```bash\n   sudo dpkg -i docker-dns-1.0.2_amd64.deb\n   ```\n\n### Configuration\n\n1. **Check the Service Status**:\n    - Ensure the service is running:\n      ```bash\n      systemctl status docker-dns\n      ```\n\n2. **Edit the Configuration (Optional)**:\n    - The configuration file is located at `/etc/docker-dns/docker-dns.conf`.\n    - Example:\n      ```ini\n      # Docker DNS Configuration\n      IP=127.0.0.153\n      TTL=300\n      TLD=docker,local\n      DEFAULT_RESOLVER=8.8.8.8,1.1.1.1,8.8.4.4\n      ```\n    - After making changes, restart the service:\n      ```bash\n      sudo systemctl restart docker-dns\n      ```\n3. **Restart the Service After Changes**:\n\n* If you edit the configuration file, restart the service to apply changes:\n    ```bash\n    sudo systemctl restart docker-dns\n    ```\n\n---\n\n## Usage\n\n1. **Resolve containers by their names**\n\n- Assuming a container named `mycontainer` is running, and that `docker-dns` has been configured to listen on ip\n  `127.0.0.153`, and the TLD is `.docker`, let's resolve the container's IP:\n   ```bash\n   dig mycontainer.docker @127.0.0.153 +short\n   ```\n\n2. **Resolve external domains**\n\n- Check that `docker-dns` is also capable of resolving domains which are not \"internal\" docker container names\n- Verify non-Docker queries are forwarded to the fallback DNS:\n   ```bash\n   dig google.com @127.0.0.153 +short\n   ``` \n\n---\n\n## Full Configuration Details\n\n* It is possible to configure the `docker-dns` server at startup time through a couple of CLI arguments\n* The `systemd` setup of the application uses an INI-style configuration file located at\n  `/etc/docker-dns/docker-dns.conf`.\n* Below is an explanation of the configurable options:\n\n### `--ip` (INI file variable name: `IP`)\n\n- The ip address the DNS server listens on (default: `127.0.0.153`).\n- Typically, it would be within the loop-back range (```127.0.0.0/8```), but could also be an IP for a customer\n  interface.\n- Default: `127.0.0.153`\n- Change this value if another service (e.g., a DNS server) is already using this IP, or if you target another\n  interface.\n- Example: if you don't have any DNS server already listening on the localhost IP (`127.0.0.1`), you can start\n  `docker-dns` as such:\n    - ```bash\n    ./sudo docker-dns --ip=127.0.0.1\n    ```\n\n### `--ttl` (INI file variable name:  `TTL` )\n\n- The time-to-live (in seconds) for cached DNS records (default: `300`).\n- Use a higher value for less frequent updates (better performance)\n- Use a lower value for more real-time accuracy.\n\n### `--tld` (INI file variable name:  `TLD`)\n\n- A comma-separated list of top-level domains for resolving container names (default: `docker`).\n- Example: if ```TLD=docker,local``` and a container's name is ```mycontainer```, queries to both\n  ```mycontainer.docker``` and ```mycontainer.local``` will resolve to the container's IP.\n\n### `--resolvers` (INI file variable name:  `DEFAULT_RESOLVER`)\n\n- A comma-separated list of fallback DNS servers (default: `8.8.8.8,1.1.1.1,8.8.4.4`).\n- These are used when a query cannot be resolved via Docker-based DNS.\n- Examples:\n    - ```8.8.8.8``` (Google DNS)\n    - ```1.1.1.1``` (Cloudflare DNS)\n    - ```127.0.0.1``` (Some Local DNS server)\n- Notes:\n    - Specify multiple servers to provide redundancy (e.g., ```DEFAULT_RESOLVER=8.8.8.8,1.1.1.1```).\n    - To use a local DNS server for non-Docker queries, add its IP address here (e.g., ```127.0.0.1```).\n\n---\n\n## Important Notes\n\n### Default Resolver Integration\n\n- While Docker DNS runs by default on a custom IP (not `127.0.0.1`), it is possible to use tools like `dig` to test\n  queries:\n  ```bash\n       dig mycontainer.docker @127.0.0.153 +short \n  ```\n    - However, making Docker DNS the system-wide default resolver requires additional configuration or hacks.\n\n### Systemd-Resolved Compatibility: Direct integration with\n`systemd-resolved` is non-trivial and not recommended without advanced setup.\n\n### Protocol\n\n* `docker-dns` is configured to run on `UDP` mode only, so `TCP` requests won't be answered\n\n---\n\n## Build/Run from Source\n\n### Download built/compiled binaries:\n\n- Go to the [Releases](https://github.com/MedUnes/docker-dns/releases) page.\n- Pick the package that matches your OS/Environment, download and run as explained below\n\n### Build locally:\n\n- For developers, you can build the application from source:\n\n1. Clone the repository:\n   ```bash\n   git clone https://github.com/medunes/docker-dns.git\n   cd docker-dns\n   ```\n2. Build the binary:\n   ```bash\n   make build\n   ```\n\n### Run the binary:\n\n- Once you have the binary generated, you can run at as follows (linux):\n   ```bash\n   sudo ./docker-dns -h\n      Usage of docker-dns:\n   -ip string\n      IP address the DNS server listens on (default \"127.0.0.153\")\n   -tld string\n      Comma-separated managed top-level domains for container resolution (default \"docker\")\n   -ttl int\n      TTL in seconds for cache entries and DNS responses (default 300)\n   -resolvers string\n      Comma-separated fallback DNS resolver IPs (default \"8.8.8.8,1.1.1.1,8.8.4.4\")\n   -forward-timeout duration\n      Per-resolver timeout for forwarded DNS queries (default 2s)\n   ```\n- P.S: `sudo` (or `root`) is required as the server will be listening on port `53`, which is\n  a [previewed port](https://www.w3.org/Daemon/User/Installation/PrivilegedPorts.html)\n\n---\n\n## Contributing\n\nContributions are welcome!\n\n1. Fork the repository.\n2. Create a feature branch:\n   ```bash\n   git checkout -b feature/YourFeature\n   ```\n3. Commit your changes:\n   ```bash\n   git commit -am 'Add YourFeature'\n   ```\n4. Push to the branch:\n   ```bash\n   git push origin feature/YourFeature\n   ```\n5. Open a Pull Request.\n\n---\n\n## License\n\nThis project is licensed under the AGPL License - see the [LICENSE](./LICENSE) file for details.\n\n---\n\n*Empower your Docker networking with easy-to-use DNS resolution!*\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmedunes%2Fdocker-dns","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fmedunes%2Fdocker-dns","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmedunes%2Fdocker-dns/lists"}