{"id":15019100,"url":"https://github.com/cielquan/doth-dns","last_synced_at":"2026-03-06T07:03:06.316Z","repository":{"id":53483825,"uuid":"200394273","full_name":"Cielquan/DoTH-DNS","owner":"Cielquan","description":"Your server doth DNS the safe way if you use DoTH-DNS.","archived":false,"fork":false,"pushed_at":"2024-05-03T09:18:10.000Z","size":494,"stargazers_count":29,"open_issues_count":1,"forks_count":1,"subscribers_count":2,"default_branch":"main","last_synced_at":"2024-05-03T14:01:25.813Z","etag":null,"topics":["bash-script","dns-server","docker","docker-compose","doh","doh-server","dot","encryption","pi-hole","traefik","unbound"],"latest_commit_sha":null,"homepage":"","language":"Shell","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"gpl-3.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/Cielquan.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","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}},"created_at":"2019-08-03T15:59:13.000Z","updated_at":"2024-08-01T16:33:56.411Z","dependencies_parsed_at":"2023-02-12T15:40:12.644Z","dependency_job_id":"6762bad6-c990-4dd4-8470-10a29d3acc27","html_url":"https://github.com/Cielquan/DoTH-DNS","commit_stats":{"total_commits":403,"total_committers":5,"mean_commits":80.6,"dds":0.4441687344913151,"last_synced_commit":"2bb83bc58de57dc242829b3fce18a3b5642b0fca"},"previous_names":[],"tags_count":31,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Cielquan%2FDoTH-DNS","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Cielquan%2FDoTH-DNS/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Cielquan%2FDoTH-DNS/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Cielquan%2FDoTH-DNS/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/Cielquan","download_url":"https://codeload.github.com/Cielquan/DoTH-DNS/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":219866820,"owners_count":16555824,"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":["bash-script","dns-server","docker","docker-compose","doh","doh-server","dot","encryption","pi-hole","traefik","unbound"],"created_at":"2024-09-24T19:52:59.277Z","updated_at":"2025-10-24T03:31:55.579Z","avatar_url":"https://github.com/Cielquan.png","language":"Shell","funding_links":[],"categories":[],"sub_categories":[],"readme":"# DoTH-DNS\n\n**Your server _doth_ DNS the safe way if you use DoTH-DNS.**\n\n[![pre-commit.ci status](https://results.pre-commit.ci/badge/github/Cielquan/DoTH-DNS/main.svg)](https://results.pre-commit.ci/latest/github/Cielquan/DoTH-DNS/main)\n![GitHub License](https://img.shields.io/github/license/Cielquan/DoTH-DNS?style=flat-square)\n![GitHub release (latest SemVer)](https://img.shields.io/github/v/release/Cielquan/DoTH-DNS?logo=github\u0026style=flat-square)\n![GitHub commits since latest release (by SemVer)](https://img.shields.io/github/commits-since/Cielquan/DoTH-DNS/latest?logo=github\u0026style=flat-square)\n![GitHub last commit](https://img.shields.io/github/last-commit/Cielquan/DoTH-DNS?logo=github\u0026style=flat-square)\n![GitHub Repo stars](https://img.shields.io/github/stars/Cielquan/DoTH-DNS?logo=github\u0026style=flat-square)\n![GitHub forks](https://img.shields.io/github/forks/Cielquan/DoTH-DNS?logo=github\u0026style=flat-square)\n![GitHub contributors](https://img.shields.io/github/contributors/Cielquan/DoTH-DNS?logo=github\u0026style=flat-square)\n\nUtilizes the power of the DNS sinkhole [pi-hole][main-pihole] and the recursive DNS resolver\n[unbound][main-unbound] to create a DNS server under your own authority with the added benefit\nto be able to also use encrypted Transport Protocols.\n\nBy default DNS traffic is send unencrypted to port 53 also called Do53 (DNS over port 53).\nDNS over HTTPS ([DoH][main-doh]) and DNS over TLS ([DoT][main-dot]) are both **encrypted**\nalternative Transport Protocols which are both supported by the DoTH-DNS stack, hence the name.\n\n[main-pihole]: https://pi-hole.net\n[main-unbound]: https://www.nlnetlabs.nl/projects/unbound/about\n[main-doh]: https://en.wikipedia.org/wiki/DNS_over_HTTPS\n[main-dot]: https://en.wikipedia.org/wiki/DNS_over_TLS\n\n## Disclaimer\n\nThis project is **not** actively maintained. Nonthenless are issues or PRs welcome.\n\nThe versioning and development of this project is rather wild. In its core it was always the same:\nbringing docker containers up to run the DoTH-DNS stack, but the way this is achieved changes over\nthe course of different versions. You may see the [Changelog](Changelog.rst) for more information.\nThis means also that the handling of the stack may change in future versions.\n\nUse at own risk see the License file for more details.\n\n**WARNING:**\nThis project was created for use in a local network. If you want to use it on a VPS or in an\ncloud environment be sure to properly secure your environment and know what you do.\n\n## Usage\n\n### Prerequisites and what to know before starting\n\n#### Operating system\n\nIn the following section I explain how to run the stack on ubuntu. If you use another linux distro\nthe commands shown may differ.\n\nI don't own a Mac and don't use Windows for such things, so I can not help you there. You will have\nto modify this guide to fit your system yourself. Sorry.\n\n#### Processor architecture\n\nI run this stack on a _x86_ maschine. If you want to run this on an _ARM_ maschine, e.g.\nRaspberryPi you need to make some adjustments.\n\n**WARNING:**\nI did not test these changes in practice.\n\n1. _pihole_ and _traefik_ should work fine as is.\n1. The _doh_server_ image needs to be build on the host anyways.\n1. The _unbound_ image needs to change to the `mvance/unbound-rpi` image by changing it in the\n   [docker-compose.yaml](docker-compose.yaml) file.\n\n#### SSL Certificates\n\nBecause of the TLS encryption we need certificates accordingly.\n\ntraefik proxy supports different setups for certificates:\n\n1. By default traefik creates a self signed wildcard certificate.\n\n   This is ok for testing and works\n   in the sense that a TLS secured connection can be established, but your browser will complain\n   that the connection is not secure. I am not sure but this will most certainly block when\n   trying to establish a DoH or DoT connection.\n\n1. Self configured certificates - self-signed and/or official ones.\n\n   Here you need to pass the certificate files into the docker\n   container yourself and also configure a certificate store for traefik by updating the\n   [docker-compose.yaml](docker-compose.yaml) file.\n\n   See traefik's documention for more information (link in the [resources section](#resources--help)).\n\n1. Automatic generation of certificates with [letsencrypt][letsencrypt] and the ACME protocol.\n\n   letsencrypt is a nonprofit Certificate Authority (CA) and provides free and automated\n   certificates. Only caveat is that you need a _real_ domain and a domain registrar that is\n   supported by the lego library which traefik uses, but there are a lot of supported ones.\n\n   See traefik's documention for more information (link in the [resources section](#resources--help)).\n\n   Because the certification process is easily automated I use this approach with my domain from\n   [name.com][namecom].\n   This approach also works when the stack, like mine, only runs in your LAN and is not visible to\n   the internet, thanks to the _DNS-01 challenge_.\n\n[letsencrypt]: https://letsencrypt.org\n[namecom]: https://name.com\n\n#### Additional Software\n\n1. To get the source we use _git_. Alternatively you could download the zip archive and extract it.\n1. To run the stack we need _docker_ and _docker-compose_.\n\n   You need root permissions to work with docker. To remove the need of using sudo, you can add the\n   `docker` group to your user. After adding the group you need to log out and in again.\n\n   ```console\n   sudo usermod -aG docker USERNAME\n   ```\n\n1. To create a user/password combo for the [`.htpasswd`][htpasswd] file for password protection\n   of the traefik dashboard we need the _htpasswd_ utility from the _apache2-utils_ package.\n   Alternatively you can use e.g. this [online tool][htpasswd-gen].\n1. To edit files I use the _nano_ text editor.\n\nTo install all run this:\n\n```console\nsudo apt install git docker.io docker-compose apache2-utils nano\n```\n\n[htpasswd]: https://en.wikipedia.org/wiki/.htpasswd\n[htpasswd-gen]: https://wtools.io/generate-htpasswd-online\n\n### Configuration\n\n#### `.env` file\n\nThe run configuration is done inside the `.env` file in the root directory of this repository.\n\n- HOST_IP - (**Mandatory**)\n\n  This is the IPv4 address of the docker host system and is needed for pihole.\n\n- DOMAIN - (**Mandatory**)\n\n  This is the domain you want to use for your DNS server.\n\n- HOSTNAME - (Optional; defaults to `dns_server`)\n\n  This sets the hostname of the containers.\n\n- PIHOLE_WEBPASSWORD - (Optional; unset by default -\u003e no password)\n\n  The password you want to use for the pihole dashboard. Can be changed again later.\n\n- TIMEZONE - (Optional; defaults to Europe/Berlin)\n\n  TZ database name of your timezone which gets uses for timestamps etc.\n\n  You can see a list of thouse names at\n  [link](https://en.wikipedia.org/wiki/List_of_tz_database_time_zones).\n\n- ACME_EMAIL - (**Mandatory**)\n\n  Email address used for registration at letsencrypt (no account needed).\n\n- ACME_CASERVER - (Optional; defaults to \u003chttps://acme-v02.api.letsencrypt.org/directory\u003e)\n\n  This is the server to get the certificates from. By default the _production_ server is used.\n  When you test things you should set the _staging_ server to avoid the weekly rate limiting.\n\n  Staging server: \u003chttps://acme-staging-v02.api.letsencrypt.org/directory\u003e\n\n- ACME_DNSCHALLENGE_PROVIDER - (Optional; defaults to namedotcom)\n\n  The domain registrar or the DNS provider for your domain, if they are not the same.\n\n- NAMECOM_USERNAME - (Optional; unset by default)\n\n  This is you name.com username.\n\n- NAMECOM_API_TOKEN - (Optional; unset by default)\n\n  This is your name.com API Token, which you can create at\n  [link](https://www.name.com/account/settings/api).\n\n#### DoH Server\n\nIf you need to modify the DoH server config, what you most certainly not, you can find the config\nfile here: `doh-docker/data/doh-server.conf`.\n\n#### pihole\n\nThe pihole configuration files and directory you can find here: `pihole-docker/data`.\n\n#### traefik\n\nIf you need to create a traefik config file put it here: `traefik-docker/data`.\n\n#### unbound\n\nIf you need to modify the unbound boot script, what you most certainly not, you can find it here:\n`unbound-docker/scripts/unbound.sh`.\n\nunbound's config files can be found here: `unbound-docker/data/unbound.conf.d`. Here you most\ncertainly only want to change things in the `default.conf` file or add another custom file.\n\n### Step by Step Setup\n\nAll following steps are run from the command line:\n\n1. Git clone this repository via HTTPS:\n\n   ```console\n   git clone https://github.com/Cielquan/DoTH-DNS\n   ```\n\n1. Open the directory:\n\n   ```console\n   cd DoTH-DNS\n   ```\n\n1. Build the `doh_server` docker image:\n\n   ```console\n   docker build --tag cielquan/doh_server:latest doh-docker\n   ```\n\n1. Create `.htpasswd` file for password protection of the traefik dashboard\n\n   - via the `htpasswd` utility:\n\n     ```console\n     htpasswd -c traefik-docker/data/.htpasswd USERNAME\n     ```\n\n   - or when you created the user/password combi online, create the file and copy it there:\n\n     ```console\n     nano traefik-docker/data/.htpasswd\n     ```\n\n   - If you do not want or need password protection you need to remove `TraefikAuth` from the\n     `traefik.http.routers.Traefik.middlewares` label for the traefik container in the\n     [docker-compose.yaml](docker-compose.yaml) file.\n\n1. Create a `.env` file and edit it with your configuration\n   (see [configuration section](#configuration)):\n\n   ```console\n   nano .env\n   ```\n\n1. Start all containers:\n\n   ```console\n   docker-compose up -d\n   ```\n\n### Logs\n\nIn `unbound-docker/data/var/log` you can find unbounds log file, which will be recreated each boot.\n\nAll other container do not log to a file but stdout/stderr. You can see them by running\n\n```console\ndocker-compose logs CONTAINERNAME\n```\n\n### How to use the DNS server stack\n\n#### Do53\n\nTo normally use your new DNS server simply provide your set `HOST_IP` as your DNS server e.g. in\nyour DHCP server.\n\n#### DoH\n\nTo use DoH you need to set `https://doh.DOMAIN/dns-query` URL in the corresponding DoH settings\nof your used software.\n\n#### DoT\n\nTo use DoT you either need to set `https://dot.DOMAIN` URL or `HOST_IP` with port 853 in the DoT\nsettings of your used software.\n\n#### pihole\n\nAt the URL `https://pihole.DOMAIN` you can find the pihole dashboard where you can set your\nblocklists, etc.\n\n#### traefik\n\nAt the URL `https://traefik.DOMAIN` you can find the traefik dashboard which has only informational\nuse.\n\n### Updates\n\nWhen there are new version of one or more of the used containers simply replace the container.\nBecause the configuration of all containers is mapped to directories and files outside, they are preserved.\n\n1. Stop the container\n\n   ```console\n   docker-compose stop CONTAINERNAME\n   ```\n\n1. Remove the container\n\n   ```console\n   docker-compose rm CONTAINERNAME\n   ```\n\n1. Pull the new image\n\n   ```console\n   docker-compose pull CONTAINERNAME\n   ```\n\n1. Start the container\n\n   ```console\n   docker-compose up -d CONTAINERNAME\n   ```\n\n## Resources / Help\n\nHere are some external links for further information that may help if you have issues.\u003cbr\u003e\nIf the documention does not help, open an issue and I will try to help.\n\n- Pi-hole documentation\n  [link](https://docs.pi-hole.net)\n- Pi-hole docker image repository\n  [link](https://github.com/pi-hole/docker-pi-hole)\n- Unbound documentation\n  [link](https://www.nlnetlabs.nl/documentation/unbound)\n- Unbound docker image for x86 (normal pc)\n  [link](https://github.com/MatthewVance/unbound-docker)\n- Unbound docker image for ARM (RaspberryPi)\n  [link](https://github.com/MatthewVance/unbound-docker-rpi)\n- traefik proxy documentation\n  [link](https://docs.traefik.io/)\n- traefik proxy letsencrypt documentation\n  [link](https://doc.traefik.io/traefik/https/acme/)\n- dns-over-https repository\n  [link](https://github.com/m13253/dns-over-https)\n- dns-over-https docker image repository\n  [link](https://github.com/goofball222/dns-over-https)\n- Docker documentation\n  [link](https://docs.docker.com)\n- Similar project without DoH and DoT\n  [link](https://github.com/chriscrowe/docker-pihole-unbound)\n- Pi-hole blog post about slow loading sides and blocking QUIC protocol\n  [link](https://pi-hole.net/2018/02/02/why-some-pages-load-slow-when-using-pi-hole-and-how-to-fix-it)\n- Pi-hole guide about pi-hole + unbound\n  [link](https://docs.pi-hole.net/guides/unbound)\n- Two Blog post realizing a similar construct\n  [link 1](https://www.aaflalo.me/2018/10/tutorial-setup-dns-over-https-server)\n  [link 2](https://www.bentasker.co.uk/documentation/linux/407-building-and-running-your-own-dns-over-https-server)\n\n## FAQ\n\n### Where does the name come from\n\nFirstly the name `DoTH-DNS` is a word construct resulting from the ability to\nuse `DoT` and `DoH` for `DNS` queries.\n\nSecondly `doth` is an _[archaic word for third person singular present tense of do][doth-source]_,\nwhich matches the name perfectly well, because it `does DNS` (see slogan at top).\n\n[doth-source]: https://www.lexico.com/definition/doth\n\n### Where is the python CLI app?\n\nThe python CLI app from v7 lifes on the [`python-cli-pihole4` branch][faq-py-cli-branch] and is\nalso still available from PyPI.\n\nBecause as of now I find the CLI app solution over-engineered so I switched back to a simpler\ndocker-compose setup.\n\n**WARNING:**\nThe app was build for pihole v4 which is outdated and I am unsure if it works with\npihole v5. Also traefik proxy will release its next major version soon,\nwhich is incompatible with the config used in the app.\n\n[faq-py-cli-branch]: https://github.com/Cielquan/DoTH-DNS/tree/python-cli-pihole4\n\n## Known issues\n\n- There is an issue with `alpine linux 1.13` which breaks the build of the `doh_server`\n  container on presumably ARM hardware (e.g. RaspberryPi).\u003cbr\u003e\n  See [issue #8](https://github.com/Cielquan/DoTH-DNS/issues/8).\n\n## Acknowledgements\n\nThanks to the creators, maintainers and developers of the software and linked resources used in\nthis project.\n\nSpecial thanks to:\n\n- the [dns-over-https][ack-doh] project and its [docker version][ack-doh-docker] as a base for my\n  Dockerfile.\n- the [docker-pihole-unbound][ack-dpu-proj] project for the inspiration.\n- this [blog post][ack-blog-1] and this [blog post][ack-blog-2] for being the first foundation of\n  this project.\n\n[ack-doh]: https://github.com/m13253/dns-over-https\n[ack-doh-docker]: https://github.com/goofball222/dns-over-https\n[ack-dpu-proj]: https://github.com/chriscrowe/docker-pihole-unbound\n[ack-blog-1]: https://www.aaflalo.me/2018/10/tutorial-setup-dns-over-https-server\n[ack-blog-2]: https://www.bentasker.co.uk/documentation/linux/407-building-and-running-your-own-dns-over-https-server\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fcielquan%2Fdoth-dns","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fcielquan%2Fdoth-dns","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fcielquan%2Fdoth-dns/lists"}