{"id":30512915,"url":"https://github.com/kaczmar2/pihole-cloudflared-doh","last_synced_at":"2026-05-03T20:39:04.041Z","repository":{"id":311282844,"uuid":"1043045663","full_name":"kaczmar2/pihole-cloudflared-doh","owner":"kaczmar2","description":"Pi-hole v6 + cloudflared in Docker: A simple Docker Compose setup for Pi-hole v6 that uses cloudflared with Pi-hole to enable DNS-over-HTTPS queries to Cloudflare, Google, and other DoH providers.","archived":false,"fork":false,"pushed_at":"2025-08-24T01:33:20.000Z","size":17,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2025-08-24T11:10:31.241Z","etag":null,"topics":["cloudflared","cloudflareddns","dns-over-https","docker","docker-compose","doh","pihole","pihole-configuration"],"latest_commit_sha":null,"homepage":"","language":null,"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/kaczmar2.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,"zenodo":null}},"created_at":"2025-08-23T03:17:48.000Z","updated_at":"2025-08-24T01:26:08.000Z","dependencies_parsed_at":"2025-08-24T11:10:32.643Z","dependency_job_id":null,"html_url":"https://github.com/kaczmar2/pihole-cloudflared-doh","commit_stats":null,"previous_names":["kaczmar2/pihole-cloudflared","kaczmar2/pihole-cloudflared-doh"],"tags_count":2,"template":false,"template_full_name":null,"purl":"pkg:github/kaczmar2/pihole-cloudflared-doh","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/kaczmar2%2Fpihole-cloudflared-doh","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/kaczmar2%2Fpihole-cloudflared-doh/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/kaczmar2%2Fpihole-cloudflared-doh/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/kaczmar2%2Fpihole-cloudflared-doh/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/kaczmar2","download_url":"https://codeload.github.com/kaczmar2/pihole-cloudflared-doh/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/kaczmar2%2Fpihole-cloudflared-doh/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":32584643,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-03T06:36:36.687Z","status":"ssl_error","status_checked_at":"2026-05-03T06:36:09.306Z","response_time":103,"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":["cloudflared","cloudflareddns","dns-over-https","docker","docker-compose","doh","pihole","pihole-configuration"],"created_at":"2025-08-26T06:00:29.658Z","updated_at":"2026-05-03T20:39:04.035Z","avatar_url":"https://github.com/kaczmar2.png","language":null,"funding_links":[],"categories":[],"sub_categories":[],"readme":"# Pi-hole v6 + cloudflared (DoH) in Docker\n\n## Summary\n\nThis is a **baseline setup of Pi-hole and cloudflared** using Docker. It\nassumes that you already have a gateway/router with a\n**separate DHCP and NTP server**. If you want Pi-hole to handle DHCP,\nadditional configuration is needed.\n\nThis setup uses Cloudflare's **cloudflared**, a tunneling daemon, to connect\nPi-hole to DNS-over-HTTPS (DoH) providers like\n[1.1.1.1](https://one.one.one.one/) or [Quad9](https://quad9.net/), providing\nenhanced privacy and security for DNS queries. It follows the official\n[Pi-hole cloudeflared guide](https://docs.pi-hole.net/guides/dns/cloudflared/)\nbut adapts it for Pihole v6 and Docker Compose.\n\nIn this setup, **cloudflared does not have its own network interface**;\ninstead, it runs using **Pi-hole's network stack**\n(`network_mode: service:pihole`). This means:\n\n- **cloudflared is not exposed to the host network** but can still handle DNS-over-HTTPS queries.\n- **Pi-hole forwards all upstream DNS queries** to `127.0.0.1#5335`, where cloudflared handles DoH lookups.\n- **No additional networking configurations are needed** for cloudflared.\n\n## Prerequisites\n\nBefore you begin, ensure you are running:\n\n- A **Debian or Debian-based Linux distribution** (Ubuntu, Raspberry Pi OS, etc.)\n- [**Docker** installed](https://docs.docker.com/engine/install/)\n\n## Step 1: Create the Directory Structure for Bind Mounts\n\nBefore downloading the repository, set up the necessary directories for your\n**bind mounts**.\n\nRun the following commands:\n\n```bash\nmkdir -p ~/docker/pihole-cloudflared\nsudo mkdir -p /srv/docker/pihole-cloudflared/pihole/etc-pihole\nsudo mkdir -p /srv/docker/pihole-cloudflared/pihole/etc-dnsmasq.d\nsudo chown -R $USER:$USER /srv/docker\nchmod -R 755 /srv/docker\ncd ~/docker/pihole-cloudflared\n```\n\n### What These Commands Do\n\n- `mkdir -p ~/docker/pihole-cloudflared`: Creates a working directory in your home folder.\n- `sudo mkdir -p /srv/docker/...`: Creates **bind mounts** for Pi-hole.\n- `sudo chown -R $USER:$USER /srv/docker`: Ensures **your user owns the folders**.\n- `chmod -R 755 /srv/docker`: Sets **read/write permissions** for better access.\n\n## Step 2: Download the Repository\n\nDownload the latest version of this repository:\n\n```bash\ncurl -L -o main.tar.gz https://github.com/kaczmar2/pihole-cloudflared-doh/archive/refs/heads/main.tar.gz\ntar -xzf main.tar.gz --strip-components=1\n```\n\nThe `--strip-components=1` flag ensures the contents are extracted directly into\n`~/docker/pihole-cloudflared` instead of creating an extra subdirectory.\n\n**Note**: This setup uses cloudflared as a DNS-over-HTTPS proxy, providing\nenhanced privacy and security for DNS queries.\n\n## Step 3: Configure the DoH Provider\n\nBy default, the `.env` file is configured to use **Cloudflare's DoH service**\n(\u003chttps://cloudflare-dns.com/dns-query\u003e). If you want to use a different provider,\nedit the `DOH_PRIMARY` variable in the `.env` file before starting the\ncontainers. See the [DNS-over-HTTPS Providers table](#common-dns-over-https-providers)\nat the bottom for other options.\n\n## Step 3: Set the Pi-hole Admin Password\n\n### Automated Setup\n\nUse the automated setup script to configure your Pi-hole admin password:\n\n```bash\n./set-password.sh\n```\n\nThis script will:\n\n- Prompt you securely for a password\n- Temporarily disable the password environment variable in docker-compose.yml\n- Set the password in the Pi-hole container (writes to pihole.toml)\n- Extract and save the password hash to your `.env` file\n- Re-enable the password environment variable in docker-compose.yml\n- Restart containers with the new configuration\n- Create backups of your config files\n\nYour Pi-hole admin interface will be ready with the password you set.\n\n### Manual Setup\n\nIf you prefer the manual approach or need to troubleshoot:\n\n\u003cdetails\u003e\n\u003csummary\u003eClick to expand manual setup instructions\u003c/summary\u003e\n\n**Important**: For Pi-hole v6, environment variables override the TOML file.\nYou must temporarily comment out the password environment variable to allow\nthe TOML file to be updated.\n\n1. Comment out `FTLCONF_webserver_api_pwhash` in `docker-compose.yml`:\n\n   ```yaml\n   # FTLCONF_webserver_api_pwhash: ${WEBSERVER_PWHASH}\n   ```\n\n2. Restart containers to apply the change:\n\n   ```bash\n   docker compose down \u0026\u0026 docker compose up -d\n   ```\n\n3. Set your password in the Pi-hole container:\n\n   ```bash\n   docker exec -it pihole /bin/bash\n   pihole setpassword 'mypassword'\n   ```\n\n4. Get the hashed password from `pihole.toml`:\n\n   ```bash\n   cat /etc/pihole/pihole.toml | grep -E \"^[[:space:]]*pwhash[[:space:]]*=\"\n   exit\n   ```\n\n5. Copy the hash value and add it to your `.env` file (enclose in single quotes):\n\n   ```bash\n   WEBSERVER_PWHASH='$BALLOON-SHA256$v=1$s=1024,t=32$pZCbBIUH/Ew2n144eLn3vw==$vgej+obQip4DvSmNlywD0LUHlsHcqgLdbQLvDscZs78='\n   ```\n\n6. Uncomment the `FTLCONF_webserver_api_pwhash` environment variable in `docker-compose.yml`:\n\n   ```yaml\n   FTLCONF_webserver_api_pwhash: ${WEBSERVER_PWHASH}\n   ```\n\n7. Restart the containers:\n\n   ```bash\n   docker compose down \u0026\u0026 docker compose up -d\n   ```\n\n\u003c/details\u003e\n\n## Step 4: Verify cloudflared Is Working\n\nTo confirm cloudflared is resolving queries correctly, run the following\ncommands **in the pihole container**:\n\nOpen a `bash` shell in the container:\n\n```bash\ndocker exec -it pihole /bin/bash\n```\n\nTest that cloudflared is operational:\n\n```bash\ndig pi-hole.net @127.0.0.1 -p 5335\n```\n\nThe first query may be quite slow, but subsequent queries should be fairly\nquick.\n\n## Step 5: Access the Pi-hole Web Interface\n\nOnce running, open your web browser and go to:\n\n```bash\nhttp://\u003cyour-server-ip\u003e/admin/\n```\n\nLogin using the password you set.\n\n## Step 6: Secure Web Interface With SSL (Optional)\n\nFor enhanced security, see my other guides on **configuring SSL encryption**\nfor the Pi-hole web interface.\n\n- [Pi-hole v6 + Docker: Automating Let's Encrypt SSL Renewal with Cloudflare DNS](https://gist.github.com/kaczmar2/027fd6f64f4e4e7ebbb0c75cb3409787#file-pihole-v6-docker-le-cf-md)\n\n## Check Docker logs\n\nThis will show logs for both the `pihole` and `cloudflared` containers.\n\n```bash\ndocker logs pihole\ndocker logs cloudflared-doh\n```\n\n## Notes\n\n### Common DNS-over-HTTPS Providers\n\n| Provider | DoH Endpoint |\n|----------|-------------|\n| [Cloudflare](https://one.one.one.one) | \u003chttps://cloudflare-dns.com/dns-query\u003e |\n| [Quad9](https://quad9.net/service/service-addresses-and-features) | \u003chttps://dns.quad9.net/dns-query\u003e |\n| [Google](https://developers.google.com/speed/public-dns/docs/doh) | \u003chttps://dns.google/dns-query\u003e |\n| [OpenDNS](https://support.opendns.com/hc/en-us/articles/360038086532-Using-DNS-over-HTTPS-DoH-with-OpenDNS) | \u003chttps://doh.opendns.com/dns-query\u003e |\n\n**Note**: To use a different DoH provider, update the `DOH_PRIMARY` variable\nin your `.env` file with the desired endpoint from the table above.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fkaczmar2%2Fpihole-cloudflared-doh","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fkaczmar2%2Fpihole-cloudflared-doh","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fkaczmar2%2Fpihole-cloudflared-doh/lists"}