{"id":15148277,"url":"https://github.com/davidgarciacat/pihole-dnscrypt","last_synced_at":"2026-02-19T16:33:23.479Z","repository":{"id":165301467,"uuid":"640648495","full_name":"DavidGarciaCat/pihole-dnscrypt","owner":"DavidGarciaCat","description":"Filter unhealthy DNS queries with Pi-hole and DNSCrypt to keep your local network safe (one of the most straightforward and most desirable projects for your Raspberry Pi)","archived":false,"fork":false,"pushed_at":"2024-05-31T13:38:29.000Z","size":12,"stargazers_count":5,"open_issues_count":0,"forks_count":1,"subscribers_count":3,"default_branch":"master","last_synced_at":"2025-01-30T22:42:14.562Z","etag":null,"topics":["adware-blocking","dns","dns-filter","dns-server","dnscrypt","dnscrypt-proxy","dnsfilter","docker","docker-compose","fake-news","gambling-filter","malware-block","mit-license","pi-hole","pihole","porn-filter","raspberry-pi","social-media-filter","telemetry-filter","tracking-blocker"],"latest_commit_sha":null,"homepage":"","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/DavidGarciaCat.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}},"created_at":"2023-05-14T19:20:29.000Z","updated_at":"2024-09-29T16:01:05.000Z","dependencies_parsed_at":"2024-05-31T15:05:34.911Z","dependency_job_id":null,"html_url":"https://github.com/DavidGarciaCat/pihole-dnscrypt","commit_stats":null,"previous_names":[],"tags_count":0,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/DavidGarciaCat%2Fpihole-dnscrypt","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/DavidGarciaCat%2Fpihole-dnscrypt/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/DavidGarciaCat%2Fpihole-dnscrypt/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/DavidGarciaCat%2Fpihole-dnscrypt/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/DavidGarciaCat","download_url":"https://codeload.github.com/DavidGarciaCat/pihole-dnscrypt/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":237910078,"owners_count":19385829,"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":["adware-blocking","dns","dns-filter","dns-server","dnscrypt","dnscrypt-proxy","dnsfilter","docker","docker-compose","fake-news","gambling-filter","malware-block","mit-license","pi-hole","pihole","porn-filter","raspberry-pi","social-media-filter","telemetry-filter","tracking-blocker"],"created_at":"2024-09-26T13:02:04.553Z","updated_at":"2025-10-24T03:31:28.062Z","avatar_url":"https://github.com/DavidGarciaCat.png","language":"Shell","funding_links":[],"categories":[],"sub_categories":[],"readme":"# DNS filtering with Pi-hole + DNSCrypt\n\nFilter unhealthy DNS queries to prevent:\n\n- adware\n- malware\n- tracking\n- telemetry\n- fake news\n- gambling\n- porn\n- social media\n\nAs per today's date, Docker's Pi-hole version is 5.x.\n\n## Requisites\n\nThis project needs the following dependencies:\n\n- Docker + Docker Compose: https://docs.docker.com/engine/install/\n- `make` command/binary. Please check how to enable it in your operating system if you don't have it.\n\n## Install and launch\n\nCreate a `download.sh` file from the templated version:\n\n```shell\ncp s6-overlay/download.sh.tpl\nchmod 755 s6-overlay/download.sh\n```\n\nEdit the `download.sh` file to set the desired S6 Overlay version and the required server architecture\n\n\u003e Please note I am working with an Apple M1 laptop so I need the `arm` architecture. If you work with an Intel or AMD CPU, then you will probably need the `x86_64` architecture.\n\nRun the `make` command to boot up the system:\n\n```shell\nmake up\n```\n\nIt will perform the following actions:\n\n- Download and prepare the required versions of S6 Overlay\n- Build and run the DNSCrypt service to perform DNS checks via HTTPS\n- Build and run the PiHole service to filter unwanted content\n\nIf you ever need to stop the containers, you can use the `make` command again:\n\n```shell\nmake down\n```\n\n## Post-install configuration\n\nOnce the system has boot, make sure to change the PiHole password for the one you want:\n\n```\n# Login into the PiHole container\ndocker-compose exec pihole bash\n\n# Change PiHole password\npihole -a -p\n\n# Don't forget to exit the container's bash\nexit\n```\n\n## Management\n\nAfter setting your admin password, you will need to set the DNS Crypt service as your primary resolver:\n\n- Browse your server's IP address and log into the system:\n  - http://0.0.0.0:8088/admin/ (you will need to type your recently set password)\n- Then browse the `Settings` option from the sidebar menu, and click on the `DNS` tab.\n- Disable any active `Upstream DNS Servers` service\n- Enable the first `Custom Upstream DNS Servers` and set the DNS Crypt IP Address:\n  - `172.20.0.3`\n- Make sure to save the changes (the `Save` button is at the bottom)\n\nYou will also need to add one or more black lists of hosts to prevent their access:\n\n- There is already a pre-loaded list. However it only prevents \"adware \u0026 malware\". You might want to change it by another one:\n  - https://github.com/StevenBlack/hosts#list-of-all-hosts-file-variants\n- Then browse the `Adlists` option from the sidebar menu.\n- Add the URL of the list you want to add (and set a comment for it if needed). Then add it clicking the `Add` button.\n- Under the `List of adlists` block, make sure to enable or disable the lists according to your needs.\n\nPersist the changes!!\n\n- Browse the `Tools` option from the sidebar menu, and then click on the `Update Gravity` submenu.\n- Click on the `Update` button; otherwise your previous configuration might not be working unless you reboot the containers.\n\n## Enable the DNS filter on your network\n\nIf you want to use this service on a specific devices, then configure the DNS server on that device to target your Pi-hole + DNSCrypt server.\n\nIf you want to use this service for your entire network, then configure the DNS server on your router or NAT networks to target your Pi-hole + DNSCrypt server.\n\nIf this project is not running in a home environment, then you might want to consider booting up two instances of this service in two different servers. This way, you can consider a secondary DNS server in case you run maintenance actions.\n\n## Apple's Private Relay\n\nBy default, Pi-hole blocks `Apple Private Relay` connections. It is not possible to allow them through Pi-hole whitelists.\n\nIf you wish to allow Apple Private Relay connections, stop the containers (`make down`), and add the following configuration to your Pi-hole config files:\n\n```conf\n# pihole/etc-pihole/pihole-FTL.conf\n\n# ...\nBLOCK_ICLOUD_PR=false\n# ...\n```\n\n## Troubleshooting\n\n**ERROR: Pool overlaps with other one on this address space**\n\nThe error message you're encountering suggests that the IP address range you specified for the bridge network in Docker overlaps with another existing network. Docker requires unique IP address ranges for each network to avoid conflicts.\n\nYour options are:\n\n1. Update the `docker-compose.yaml` file and assign a new IP Address range; or\n2. Update the existing networks if you run more than one Docker project to release the range used in this project\n\n## Resources\n\nRead more about the used tech here:\n\n- **Pi-hole - Network-wide Ad Blocking**\n  - https://pi-hole.net/\n- **DNSCrypt**\n  - https://www.dnscrypt.org/\n  - https://en.wikipedia.org/wiki/DNSCrypt\n- **Steven Black's hosts blacklists**\n  - https://github.com/StevenBlack/hosts\n- **S6 Overlay**\n  - https://github.com/just-containers/s6-overlay\n\n## Thanks\n\nSpecial thanks to:\n\n- My friend @KatsuroKurosaki for sharing a base/split implementation of this project, as I used it as a base guide/reference to create this repository\n- All the creators and maintainers of `Pi-hole`, `DNSCrypt`, `blacklists` and `S6 Overlay` as this project would no exist without their unvaluable contribution\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fdavidgarciacat%2Fpihole-dnscrypt","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fdavidgarciacat%2Fpihole-dnscrypt","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fdavidgarciacat%2Fpihole-dnscrypt/lists"}