{"id":20075001,"url":"https://github.com/master-hax/compose-cloudhole","last_synced_at":"2026-05-08T04:13:42.476Z","repository":{"id":193628416,"uuid":"451297317","full_name":"master-hax/compose-cloudhole","owner":"master-hax","description":"a multi-container application to run pi-hole with cloudflared DNS-over-HTTPS as the upstream resolver","archived":false,"fork":false,"pushed_at":"2023-01-08T09:36:35.000Z","size":25,"stargazers_count":2,"open_issues_count":0,"forks_count":0,"subscribers_count":1,"default_branch":"master","last_synced_at":"2025-07-18T05:37:23.669Z","etag":null,"topics":["ad-block","ad-blocker","dns","dns-over-https","dns-server","dnsmasq","docker","docker-compose","pi-hole","pihole","privacy","security"],"latest_commit_sha":null,"homepage":"","language":null,"has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/master-hax.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null}},"created_at":"2022-01-24T03:00:25.000Z","updated_at":"2023-01-05T17:58:42.000Z","dependencies_parsed_at":"2023-09-09T05:27:05.254Z","dependency_job_id":"6351de1b-5642-4907-b109-5d10acfc6cc5","html_url":"https://github.com/master-hax/compose-cloudhole","commit_stats":null,"previous_names":["master-hax/compose-cloudhole"],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/master-hax/compose-cloudhole","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/master-hax%2Fcompose-cloudhole","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/master-hax%2Fcompose-cloudhole/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/master-hax%2Fcompose-cloudhole/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/master-hax%2Fcompose-cloudhole/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/master-hax","download_url":"https://codeload.github.com/master-hax/compose-cloudhole/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/master-hax%2Fcompose-cloudhole/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":32766287,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-08T02:36:36.067Z","status":"ssl_error","status_checked_at":"2026-05-08T02:36:07.210Z","response_time":54,"last_error":"SSL_read: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"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":["ad-block","ad-blocker","dns","dns-over-https","dns-server","dnsmasq","docker","docker-compose","pi-hole","pihole","privacy","security"],"created_at":"2024-11-13T14:57:02.325Z","updated_at":"2026-05-08T04:13:42.462Z","avatar_url":"https://github.com/master-hax.png","language":null,"funding_links":[],"categories":[],"sub_categories":[],"readme":"# compose-cloudhole\n\na multi-container Docker application to run a [pi-hole](https://hub.docker.com/r/pihole/pihole) ad-blocking DNS server that uses a [cloudflared](https://hub.docker.com/r/visibilityspots/cloudflared) DNS over HTTPS proxy as the upstream resolver\n\n## how to set it up\n\n1. download [docker-compose.yml](/docker-compose.yml)\n1. create a file named `pwd` containing the desired password for the web interface\n1. run `docker-compose up`\n\nif everything works correctly, you should be able to resolve hosts securely \u0026 without ads on port 53!\n\n## how to use it\n\nthe DNS resolver should be accessible at `0.0.0.0:53`\n\nthe pi-hole web UI should be accessible at `0.0.0.0:54` i.e. http://localhost:54/admin\n\n### to use cloudhole for all containers:\nset Docker host to use `127.0.0.1` as the DNS resolver. all your containers will use pi-hole automatically through the Docker engine.\n\n**note**: don't set the Docker host to use its own external/LAN IP address as the resolver (as you might through DHCP), see below\n\n### to override a specific container with cloudhole:\n```\nservices:\n application:\n  dns:\n   - 172.16.1.4 # cloudhole's local IP\n```\n\n### to override a specific container with an arbitrary DNS resolver:\n```\nservices:\n application:\n  dns:\n   - 127.0.0.11 # built in docker engine DNS proxy, uses host's resolver\n   - 8.8.8.8    # google plaintext DNS\n   - 1.1.1.1    # cloudflare plaintext DNS\n```\n\nto use cloudhole across all devices on your network, give your Docker host a static IP address \u0026 advertise it using your router's DHCP server. you can go one step further and set up firewalls to block all outbound (UDP) traffic to port 53 as the DNS traffic from cloudflared will manifest as encrypted TCP traffic to port 443.\n\n### note for Docker hosts using DHCP:\n\nif your Docker host is set to use its own external IP address as the DNS resolver (that it might have gotten via DHCP from your router), this will break DNS resolution for your containers. the reason for this is that the DNS requests that are addressed externally will reach the pi-hole but the packets won't reach the containers on their way back.\n\nhowever using a static `127.0.0.1` on the host or `172.16.1.4` in the container works fine \u0026 the Docker engine is able to route the responses successfully.\n\n## how it works\n\nthe `dns-server` service (pi-hole) \u0026 the `doh-client` service (cloudflared) have static IP addresses on a local docker network, which allows them to communicate without DNS resolution being available. port 53 on the host is mapped to `dns-service` to allow it to receive requests from the outside network. pi-hole blocks some of these requests if they are for ad servers, \u0026 responds to some of them from its cache.\n\nthe rest of the requests are then sent to the upstream DNS resolver, `doh-client`, which sends them out of your network to `1.1.1.1` over [an encrypted HTTPS tunnel](https://en.wikipedia.org/wiki/DNS_over_HTTPS) rather than the default plaintext UDP packets.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmaster-hax%2Fcompose-cloudhole","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fmaster-hax%2Fcompose-cloudhole","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmaster-hax%2Fcompose-cloudhole/lists"}