{"id":13495424,"url":"https://github.com/ruudud/devdns","last_synced_at":"2025-03-28T16:32:29.866Z","repository":{"id":45503332,"uuid":"42987236","full_name":"ruudud/devdns","owner":"ruudud","description":"Automagic Docker DNS for local development","archived":false,"fork":false,"pushed_at":"2021-03-22T12:59:24.000Z","size":69,"stargazers_count":189,"open_issues_count":2,"forks_count":35,"subscribers_count":6,"default_branch":"master","last_synced_at":"2024-10-31T10:36:43.918Z","etag":null,"topics":["devdns","dns","dnsmasq","docker"],"latest_commit_sha":null,"homepage":null,"language":"Shell","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/ruudud.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}},"created_at":"2015-09-23T08:07:06.000Z","updated_at":"2024-10-30T10:43:05.000Z","dependencies_parsed_at":"2022-07-15T09:17:06.644Z","dependency_job_id":null,"html_url":"https://github.com/ruudud/devdns","commit_stats":null,"previous_names":[],"tags_count":1,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ruudud%2Fdevdns","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ruudud%2Fdevdns/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ruudud%2Fdevdns/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ruudud%2Fdevdns/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/ruudud","download_url":"https://codeload.github.com/ruudud/devdns/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":246062962,"owners_count":20717714,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","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":["devdns","dns","dnsmasq","docker"],"created_at":"2024-07-31T19:01:34.607Z","updated_at":"2025-03-28T16:32:29.570Z","avatar_url":"https://github.com/ruudud.png","language":"Shell","funding_links":[],"categories":["Shell"],"sub_categories":[],"readme":"# devdns\nMake docker containers discoverable via DNS for development environments, like\nwhen running a bunch of containers on your laptop. Useful for\n**container to container communication**, or just an easy way of **reaching\ncontainers from the host machine**.\n\n![Image Size](https://img.shields.io/microbadger/image-size/ruudud/devdns)\n![Docker Pulls](https://img.shields.io/docker/pulls/ruudud/devdns)\n![Lint](https://github.com/ruudud/devdns/workflows/Lint/badge.svg?event=push)\n\n## Running\n\n```sh\ndocker run -d --name devdns -p 53:53/udp \\\n      -v /var/run/docker.sock:/var/run/docker.sock:ro ruudud/devdns\n```\n\ndevdns requires access to the Docker socket to be able to query for container\nnames and IP addresses, in addition to listen to start/stop events.\n\nBinding port 53 on the host machine is optional, but will make it easier when\nconfiguring local resolving.\n\nThe DNS server running in devdns is set to proxy requests for unknown hosts to\nthe configured fallback DNS (default Google's DNS server 8.8.8.8).\nIt also adds a wildcard record (normally `*.test`, see `DNS_DOMAIN` below)\npointing back at the host machine (bridge IP in Linux), to facilitate\ncommunication when running a combination of services \"inside\" and \"outside\" of\nDocker.\n\n\n## Using\n\n### Container ↔ Container\nWhen running other containers, specify the devdns container IP as the DNS to\nuse:\n\n```sh\n$ docker run -d --name devdns -p 53:53/udp \\\n  -v /var/run/docker.sock:/var/run/docker.sock:ro ruudud/devdns\n$ docker run -d --name redis redis:alpine\n$ docker run -it --rm \\\n  --dns=`docker inspect -f \"{{ range.NetworkSettings.Networks }}{{ .IPAddress }}{{ end }}\" devdns | head -n1` alpine \\\n  ping redis.test\n```\n\nPlease note that the `--dns` flag will prepend the given DNS server to the\nDocker default, so lookups for external addresses will still work.\n\n#### Docker Daemon Configuration\nIf you want devdns to be added by default to all new containers, you need to\nadd some custom Docker daemon options as per the [dockerd reference][].\n\nThe exact process to set these options varies by the way you launch the Docker\ndaemon and/or the underlying OS:\n\n * systemd (Ubuntu, Debian, RHEL 7, CentOS 7, Fedora, Archlinux) —\n   `sudo systemctl edit docker.service`, change the `ExecStart` line\n * Ubuntu 12.04 — set `DOCKER_OPTS` in `/etc/default/docker`\n * OS/X — select *Preferences* -\u003e *Daemon* -\u003e *Advanced*\n\nThe extra flags you'll have to add are\n\n    --dns 172.17.0.1 --dns-search test\n\nReplace `test` with whatever you set as config for `DNS_DOMAIN`.\n\n`172.17.0.1` is the default IP of the Docker bridge, and port 53 on this host\nshould be reachable from within all started containers given that you've\nincluded `-p 53:53/udp` when starting the devdns container.\n\n\u003e Note: There are some caveats with Docker and how it manages a container's\n\u003e `/etc/resolv.conf` file. Unless you do something exotic, like parsing this\n\u003e file, you should be fine. See [Docker DNS docs][] for more information.\n\n[dockerd reference]: https://docs.docker.com/engine/reference/commandline/dockerd/#daemon-dns-options\n[Docker DNS docs]: https://docs.docker.com/v17.09/engine/userguide/networking/configure-dns/\n\n\n### Host Machine → Containers\nYou will need to add some configuration to your OS DNS resolving mechanism to\nmake it query devdns.\n\n**NOTE**: This is only practical if you added `-p 53:53/udp` when starting\ndevdns.\n\n#### Linux\nNowadays, direct edits of `/etc/resolv.conf` will often be removed at reboot.\nThus, the best place to add extra resolvers in Linux, is to use your network\nconfigurator. YMMV. This means NetworkManager (see [section\nbelow](#networkmanager-on-ubuntu)), WICD, or manually using\n`/etc/network/interfaces`:\n\n```\nauto p3p1\niface p3p1 inet dhcp\ndns-search test\ndns-nameservers 127.0.0.1\n```\n\n##### Managed `resolv.conf`\nAnother solution is mounting the host machine's `/etc/resolv.conf` at\n`/mnt/resolv.conf` and have devdns automatically add configuration on startup:\n\n```sh\ndocker run -d -v /var/run/docker.sock:/var/run/docker.sock:ro \\\n      -v /etc/resolv.conf:/mnt/resolv.conf \\\n      ruudud/devdns\n```\n\nExample config prepended to `/etc/resolv.conf`:\n```\nnameserver 192.168.16.2 # added by devdns\n```\nThe configuration will be automatically removed when container is stopped or\nkilled.\n\n\u003e :warning: **It's common that `/etc/resolv.conf` becomes overwritten** as\n\u003e many operating systems now manage the creation of that file, and in some\n\u003e cases not even rely on it at all.\n\n#### OSX\nCreate a file `/etc/resolver/test` containing\n\n    nameserver 127.0.0.1\n\nIn OSX and Docker for Mac, port binding should work directly on the host\nmachine. Please note that the name of the file created in `/etc/resolver` has\nto match the value of the `DNS_DOMAIN` setting (default \"test\").\n\n\n## Configuration\n\n * `DNS_DOMAIN`: set the local domain used. (default: **test**)\n * `FALLBACK_DNS`: set the DNS used for unknown hosts. (default: **8.8.8.8**)\n * `HOSTMACHINE_IP`: IP address of non-matching queries (default:\n   **172.17.0.1**)\n * `EXTRA_HOSTS`: list of extra records to create, space-separated string of\n   host=ip pairs. (default: **''**)\n * `NAMING`: set to \"full\" to convert `_` to `-` (default: up to first `_` of\n   container name)\n * `NETWORK`: set the network to use. Set to \"auto\" to automatically use the\n   first network interface (e.g. when using docker-compose) (default:\n   **bridge**)\n\nExample:\n\n```sh\ndocker run -d -v /var/run/docker.sock:/var/run/docker.sock \\\n  -e DNS_DOMAIN=docker \\\n  -e HOSTMACHINE_IP=192.168.1.1 \\\n  -e NAMING=full \\\n  -e NETWORK=mynetwork \\\n  -e EXTRA_HOSTS=\"dockerhost=172.17.0.1 doubleclick.net=127.0.0.1\" \\\n  ruudud/devdns\n```\n\n\n## Caveats\n\n### Container name to DNS record conversion\nRFC 1123 states that `_` are not allowed in DNS records, but Docker allows it\nin container names. devdns ignores `_` and whatever follows, allowing multiple\nsimultaneous containers with matching names to run at the same time.\n\nThe DNS will resolve to the lastly added container, and try to re-toggle the\nprevious matching container when stopping the currently active one.\n\nExample:\n```sh\n# (devdns already running)\n$ docker run -d --name redis_local-V1 redis\n$ dig redis.test     # resolves to the IP of redis_local-V1\n\n$ docker run -d --name redis_test redis\n$ dig redis.test     # resolves to the IP of redis_test\n\n$ docker stop redis_test\n$ dig redis.test     # resolves to the IP of redis_local-V1\n\n$ docker stop redis_local-V1\n$ dig redis.test     # resolves to the IP of the host machine (default)\n```\n\n### NetworkManager on Ubuntu\nIf you're using **NetworkManager**, you should disable the built-in DNSMasq to\nget the port binding of port 53 to work.\n\nEdit `/etc/NetworkManager/NetworkManager.conf` and comment out the line\n`dns=dnsmasq` so it looks like this:\n\n    # dns=dnsmasq\n\nRestart using `sudo service network-manager restart`.\n\nNow you should be able to do\n```sh\ndocker run -d -v /var/run/docker.sock:/var/run/docker.sock:ro \\\n    -p 53:53/udp ruudud/devdns\n```\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fruudud%2Fdevdns","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fruudud%2Fdevdns","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fruudud%2Fdevdns/lists"}