{"id":20643826,"url":"https://github.com/homeall/cloudflared","last_synced_at":"2026-02-09T09:12:09.118Z","repository":{"id":135232944,"uuid":"323711860","full_name":"homeall/cloudflared","owner":"homeall","description":"Custom cloudflared image in a docker environment useful for privacy.","archived":false,"fork":false,"pushed_at":"2026-01-01T01:12:03.000Z","size":769,"stargazers_count":3,"open_issues_count":1,"forks_count":1,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-01-05T15:40:00.847Z","etag":null,"topics":["cloudflared","docker","docker-environment","docker-image","doh","pihole","privacy"],"latest_commit_sha":null,"homepage":"","language":"HCL","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/homeall.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":"CONTRIBUTING.md","funding":".github/FUNDING.yml","license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":"SECURITY.md","support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null},"funding":{"github":"homeall","buy_me_a_coffee":"homeall"}},"created_at":"2020-12-22T19:09:56.000Z","updated_at":"2026-01-01T01:12:06.000Z","dependencies_parsed_at":"2023-11-21T11:27:59.009Z","dependency_job_id":"3090a73e-7ca1-40cd-84a7-296b640882db","html_url":"https://github.com/homeall/cloudflared","commit_stats":null,"previous_names":[],"tags_count":135,"template":false,"template_full_name":null,"purl":"pkg:github/homeall/cloudflared","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/homeall%2Fcloudflared","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/homeall%2Fcloudflared/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/homeall%2Fcloudflared/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/homeall%2Fcloudflared/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/homeall","download_url":"https://codeload.github.com/homeall/cloudflared/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/homeall%2Fcloudflared/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":29260426,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-02-09T04:11:57.159Z","status":"ssl_error","status_checked_at":"2026-02-09T04:11:56.117Z","response_time":56,"last_error":"SSL_connect returned=1 errno=0 peeraddr=140.82.121.5:443 state=error: 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","docker","docker-environment","docker-image","doh","pihole","privacy"],"created_at":"2024-11-16T16:13:58.366Z","updated_at":"2026-02-09T09:12:09.108Z","avatar_url":"https://github.com/homeall.png","language":"HCL","funding_links":["https://github.com/sponsors/homeall","https://buymeacoffee.com/homeall","https://img.buymeacoffee.com/button-api/?text=Buy%20me%20a%20coffee\u0026slug=homeall\u0026button_colour=FFDD00\u0026font_colour=000000\u0026font_family=Arial\u0026outline_colour=000000\u0026coffee_colour=ffffff"],"categories":[],"sub_categories":[],"readme":"[![cloudflared](https://github.com/homeall/cloudflared/workflows/CI/badge.svg)](https://github.com/homeall/cloudflared/actions)\n![Trivy Workflow Status](https://github.com/homeall/cloudflared/actions/workflows/security-scan.yml/badge.svg?branch=main)\n[![Docker](https://img.shields.io/badge/Docker-2496ED?logo=docker\u0026logoColor=fff)](#)\n[![Docker pulls](https://img.shields.io/docker/pulls/homeall/cloudflared)](https://img.shields.io/docker/pulls/homeall/cloudflared)\n[![Docker Image Size](https://img.shields.io/docker/image-size/homeall/cloudflared/latest)](https://hub.docker.com/r/homeall/cloudflared)\n[![GitHub Actions](https://img.shields.io/badge/GitHub_Actions-2088FF?logo=github-actions\u0026logoColor=white)](#) \n[![Cloudflare](https://img.shields.io/badge/Cloudflare-F38020?logo=Cloudflare\u0026logoColor=white)](#)\n[![FOSSA Status](https://app.fossa.com/api/projects/git%2Bgithub.com%2Fhomeall%2Fcloudflared.svg?type=shield\u0026issueType=license)](https://app.fossa.com/projects/git%2Bgithub.com%2Fhomeall%2Fcloudflared?ref=badge_shield\u0026issueType=license)\n[![License](https://img.shields.io/badge/license-MIT-blue.svg)](https://opensource.org/licenses/MIT)\n[![Contributions welcome](https://img.shields.io/badge/contributions-welcome-brightgreen.svg?style=flat)](https://h-all.co)\n\n# Docker image with [cloudflared](https://github.com/cloudflare/cloudflared) for *[DNS over HTTPS](https://www.cloudflare.com/en-gb/learning/dns/dns-over-tls/)*\n\n\u003c!-- TABLE OF CONTENTS --\u003e\n\u003cdetails open=\"open\"\u003e\n  \u003csummary\u003eTable of Contents\u003c/summary\u003e\n  \u003col\u003e\n    \u003cli\u003e\n      \u003ca href=\"#about-the-project\"\u003eAbout The Project\u003c/a\u003e\n    \u003c/li\u003e\n    \u003cli\u003e\n      \u003ca href=\"#getting-started\"\u003eGetting Started\u003c/a\u003e\n      \u003cul\u003e\n        \u003cli\u003e\u003ca href=\"#prerequisites\"\u003ePrerequisites\u003c/a\u003e\u003c/li\u003e\n      \u003c/ul\u003e\n    \u003c/li\u003e\n    \u003cli\u003e\n      \u003ca href=\"#usage\"\u003eUsage\u003c/a\u003e\n      \u003cul\u003e\n        \u003cli\u003e\u003ca href=\"#default-settings\"\u003eDefault Settings\u003c/a\u003e\u003c/li\u003e\n      \u003c/ul\u003e\n       \u003cul\u003e\n        \u003cli\u003e\u003ca href=\"#docker-run-command\"\u003eDocker run command\u003c/a\u003e\u003c/li\u003e\n      \u003c/ul\u003e\n       \u003cul\u003e\n        \u003cli\u003e\u003ca href=\"#custom-upstreams-and-custom-port-number\"\u003eCustom upstreams and custom port number\u003c/a\u003e\u003c/li\u003e\n      \u003c/ul\u003e\n       \u003cul\u003e\n        \u003cli\u003e\u003ca href=\"#dualstack-ipv4-ipv6\"\u003eDualstack Ipv4/IPv6\u003c/a\u003e\u003c/li\u003e\n      \u003c/ul\u003e\n    \u003c/li\u003e\n    \u003cli\u003e\u003ca href=\"#pihole\"\u003ePiHole\u003c/a\u003e\u003c/li\u003e\n    \u003cli\u003e\u003ca href=\"#license\"\u003eLicense\u003c/a\u003e\u003c/li\u003e\n    \u003cli\u003e\u003ca href=\"#contact\"\u003eContact\u003c/a\u003e\u003c/li\u003e\n  \u003c/ol\u003e\n\u003c/details\u003e\n\n## About The Project\n\nThe primary purpose of creating a custom docker image with only **[cloudflared](https://github.com/cloudflare/cloudflared)** was to use *[DNS over HTTPS](https://www.cloudflare.com/en-gb/learning/dns/dns-over-tls/)* with only **security** upstreams :arrow_down: including **three** DNSs (very good for [fail over](https://en.wikipedia.org/wiki/Failover)).\n\n:heavy_exclamation_mark:It will be very useful in Docker environment or Kubernetes where [High Availability](https://en.wikipedia.org/wiki/High-availability_cluster) is a must.\n\nI am using GitHub actions weekly where it will update cloudflared binary in order to keep up to date the docker image and the package.\n\nYou will find on the readme page how to use the commands with images.\n\nIt is advantageous for setting up together with :copyright: [PiHole](https://github.com/pi-hole/pi-hole).\n\n:no_entry_sign: If you need ADs protection and privacy, this may help you in long term.\n\n## ☕️ Support HomeAll\n\nEnjoying my home lab and IT projects?  \n[Buy me a coffee](https://buymeacoffee.com/homeall) to keep the ideas coming!\n\n[![Buy Me a Coffee](https://img.buymeacoffee.com/button-api/?text=Buy%20me%20a%20coffee\u0026slug=homeall\u0026button_colour=FFDD00\u0026font_colour=000000\u0026font_family=Arial\u0026outline_colour=000000\u0026coffee_colour=ffffff)](https://buymeacoffee.com/homeall)\n\n\u003c!-- GETTING STARTED --\u003e\n## Getting Started\n\n:beginner: It will work on any Linux box amd64 or [Raspberry Pi](https://www.raspberrypi.org) with arm64 or arm32. \n\n### Prerequisites\n\n[![Made with Docker !](https://img.shields.io/badge/Made%20with-Docker-blue)](https://github.com/homeall/cloudflared/blob/main/Dockerfile)\n\nYou will need to have:\n\n* :whale: [Docker](https://docs.docker.com/engine/install/)\n* :whale2: [docker-compose](https://docs.docker.com/compose/) \n \u003eThis step is optional\n\n\u003c!-- USAGE --\u003e\n## Usage\n\n### Default Settings\n\nIt will come with the following **security** upstreams *in this order*:\n\n* :one: 1.1.1.3\n* :two: security.cloudflare-dns.com\n* :three: 1.1.1.2\n\n:warning: Please review this [link](https://1.1.1.1/family/) in order to get more details about the upstreams above.\n\nThe default port is **54**.\n\nThe IP addres is **0.0.0.0**\n\n### Docker run command: \n\nUnless you need to change the default setting, it will work as expected with the command below:\n\n`docker run -d --name cloudflare -p \"54:54\" -p \"54:54/udp\" homeall/cloudflared:latest`\n\n:hearts: On the status column of the docker, you will notice the `healthy` word. This is telling you that docker is running [healtcheck](https://scoutapm.com/blog/how-to-use-docker-healthcheck) itself in order to make sure it is working properly. \n\n:arrow_down: Please test yourself using the following command:\n\n```\n\u003e docker inspect --format \"{{json .State.Health }}\" cloudflare | jq\n{\n  \"Status\": \"healthy\",\n  \"FailingStreak\": 0,\n  \"Log\": [\n    {\n      \"Start\": \"2021-01-04T10:42:21.5982274Z\",\n      \"End\": \"2021-01-04T10:42:21.6848715Z\",\n      \"ExitCode\": 0,\n      \"Output\": \"Server:\\t\\t127.0.0.1\\nAddress:\\t127.0.0.1#54\\n\\nName:\\tcloudflare.com\\nAddress: 104.16.133.229\\nName:\\tcloudflare.com\\nAddress: 104.16.132.229\\nName:\\tcloudflare.com\\nAddress: 2606:4700::6810:84e5\\nName:\\tcloudflare.com\\nAddress: 2606:4700::6810:85e5\\n\\n\"\n    }\n  ]\n}\n```\n:arrow_down: Docker logs output:\n\n```\nINFO[2021-01-01T20:03:37Z] Adding DNS upstream - url: https://1.1.1.3/dns-query\nINFO[2021-01-01T20:03:37Z] Adding DNS upstream - url: https://security.cloudflare-dns.com/dns-query\nINFO[2021-01-01T20:03:37Z] Adding DNS upstream - url: https://1.1.1.2/dns-query\nINFO[2021-01-01T20:03:37Z] Starting metrics server on 127.0.0.1:8080/metrics\nINFO[2021-01-01T20:03:37Z] Starting DNS over HTTPS proxy server on: dns://0.0.0.0:54\n```\n:arrow_down: Simple tests:\n\n```\n❯ dig google.com @127.0.0.1 -p 54 +short\n216.58.211.174\n❯ dig google.com @127.0.0.1 +tcp -p 54 +short\n216.58.211.174\n```\n\n![](./assets/cloudflared.gif)\n\n:arrow_up: [Go on TOP](#about-the-project) :point_up:\n\n### Custom upstreams and custom port number:  \n\nYou can change first two upstreams **DNS1** and **DNS2** and *port number*.\n\nChange to fit your needs:\n\n`docker run -d --name cloudflare -p \"5454:5454\" -p \"5454:5454/udp\" -e \"DNS1=dns.google\" -e \"DNS2=1.1.1.1\" -e \"PORT=5454\" homeall/cloudflared:latest`\n\n:arrow_down: Output result:\n\n```\nINFO[2021-01-01T20:08:36Z] Starting metrics server on 127.0.0.1:8080/metrics\nINFO[2021-01-01T20:08:36Z] Adding DNS upstream - url: https://dns.google/dns-query\nINFO[2021-01-01T20:08:36Z] Adding DNS upstream - url: https://1.1.1.1/dns-query\nINFO[2021-01-01T20:08:36Z] Adding DNS upstream - url: https://1.1.1.2/dns-query\nINFO[2021-01-01T20:08:36Z] Starting DNS over HTTPS proxy server on: dns://0.0.0.0:5454\n```\n\n![](./assets/custom-cloudflared.gif)\n\n:arrow_up: [Go on TOP](#about-the-project) :point_up:\n\n### Dualstack Ipv4 IPv6\n\n:warning: You also can use:\n\n`docker run --name cloudflare -d -p \"54:54\" -p \"54:54/udp\" -e \"ADDRESS=::\" homeall/cloudflared`\n\n:arrow_down: Output result:\n\n```\nINFO[2021-01-02T14:38:53Z] Adding DNS upstream - url: https://1.1.1.3/dns-query\nINFO[2021-01-02T14:38:53Z] Adding DNS upstream - url: https://security.cloudflare-dns.com/dns-query\nINFO[2021-01-02T14:38:53Z] Adding DNS upstream - url: https://1.1.1.2/dns-query\nINFO[2021-01-02T14:38:53Z] Starting metrics server on 127.0.0.1:8080/metrics\nINFO[2021-01-02T14:38:53Z] Starting DNS over HTTPS proxy server on: dns://[::]:54\n```\n:arrow_down: Simple tests:\n\n```\n❯ dig google.com @::1 +tcp -p 54 +short\n216.58.213.14\n❯ dig google.com @::1 -p 54 +short\n216.58.213.14\n```\n![](./assets/dualstack-cloudflared.gif)\n\n:arrow_up: [Go on TOP](#about-the-project) :point_up:\n\n## [PiHole](https://github.com/pi-hole/pi-hole)\n\n:copyright: [PiHole](https://github.com/pi-hole/pi-hole) with **cloudflared** is a match in heaven for privacy and ADs protection :bangbang:\n\n:arrow_down: Check out this [docker-compose.yml](https://docs.docker.com/compose/):\n\n```\nservices:\n  pihole:\n    container_name: pihole\n    image: pihole/pihole:latest\n    hostname: pihole\n    ports:\n      - \"53:53/tcp\"\n      - \"53:53/udp\"\n      - \"80:80/tcp\"\n    environment:\n      TZ: 'Europe/London'\n      WEBPASSWORD: 'admin'\n      ServerIP: '172.18.0.2'\n      DNS1: '172.18.0.3#54'\n      DNS2: 'no'\n    volumes:\n      - './etc-pihole/:/etc/pihole/'\n    cap_add:\n      - NET_ADMIN\n    restart: unless-stopped\n    networks:\n      pihole_net:\n        ipv4_address: 172.18.0.2\n\n  cloudflare:\n    restart: unless-stopped\n    container_name: cloudflare\n    image: homeall/cloudflared:latest\n    links:\n      - pihole\n    ports:\n      - \"54:54/tcp\"\n      - \"54:54/udp\"\n    environment:\n      TZ: 'Europe/London'\n    networks:\n      pihole_net:\n        ipv4_address: 172.18.0.3\n\nnetworks:\n  pihole_net:\n    driver: bridge\n    ipam:\n     config:\n       - subnet: 172.18.0.0/24\n```\n\u003e You will have to use the network mode and hardcoded IP address on each container to forward correctly queries to Cloudflare.\n\u003e Otherwise, you may get issues config from dnsmask.d on PiHole.\n\u003e If you use networking host mode, it will forward correctly queries to localhost on 54 port.\n\n \u003c!-- LICENSE --\u003e\n ## License\n\n:newspaper_roll: Check the [LICENSE](https://raw.githubusercontent.com/homeall/cloudflared/main/LICENSE) for more information.\n\n\u003c!-- CONTACT --\u003e\n## Contact\n\n:red_circle: Please free to open a ticket on Github. Or [![Buy Me A Coffee](https://img.shields.io/badge/Buy%20Me%20a%20Coffee-yellow?logo=buymeacoffee\u0026logoColor=white)](https://buymeacoffee.com/homeall)\n\n\n:arrow_up: [Go on TOP](#about-the-project) :point_up:\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fhomeall%2Fcloudflared","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fhomeall%2Fcloudflared","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fhomeall%2Fcloudflared/lists"}