From 7212161f7b26b1cd3d4f553a835bd1f35e5dfb0d Mon Sep 17 00:00:00 2001 From: Timothy Miller <46549361+timothymiller@users.noreply.github.com> Date: Wed, 15 Feb 2023 15:01:28 -0500 Subject: [PATCH] Updated README.md --- README.md | 150 +++++++++++++++++++++++++++++++++++++----------------- 1 file changed, 102 insertions(+), 48 deletions(-) diff --git a/README.md b/README.md index 30970b4..b7261e9 100755 --- a/README.md +++ b/README.md @@ -4,38 +4,23 @@ Access your home network remotely via a custom domain name without a static IP! -A small, πŸ•΅οΈ privacy centric, and ⚑ lightning fast multi-architecture Docker image for self hosting projects. +## ⚑ Efficiency -## πŸ“– Table of Contents +- ❀️ Easy config. List your domains and you're done. +- πŸ” The Python runtime will re-use existing HTTP connections. +- πŸ—ƒοΈ Cloudflare API responses are cached to reduce API usage. +- 🀏 The Docker image is small and efficient. +- 0️⃣ Zero dependencies. +- πŸ’ͺ Supports all platforms. +- 🏠 Enables low cost self hosting to promote a more decentralized internet. -- πŸ‡ΊπŸ‡Έ [Origin](https://github.com/timothymiller/cloudflare-ddns#-origin) -- πŸ“Š [Stats](https://github.com/timothymiller/cloudflare-ddns#-stats) -- ⁉️ [How Private & Secure Is This?](https://github.com/timothymiller/cloudflare-ddns#%EF%B8%8F-how-private--secure-is-this) -- 🧰 [Requirements](https://github.com/timothymiller/cloudflare-ddns#-requirements) -- βš’οΈ [Equipment](https://github.com/timothymiller/cloudflare-ddns#-equipment) -- 🚦 [Getting Started](https://github.com/timothymiller/cloudflare-ddns#-getting-started) - - πŸ”‘ [Authentication methods](https://github.com/timothymiller/cloudflare-ddns#-authentication-methods) - - πŸ“  [Hosting multiple subdomains on the same IP](https://github.com/timothymiller/cloudflare-ddns#-hosting-multiple-subdomains-on-the-same-ip) - - 🌐 [Hosting multiple domains (zones) on the same IP](https://github.com/timothymiller/cloudflare-ddns#-hosting-multiple-domains-zones-on-the-same-ip) -- πŸš€ [Deployment](https://github.com/timothymiller/cloudflare-ddns#-deploy-with-docker-compose) - - 🐳 [Docker Compose](https://github.com/timothymiller/cloudflare-ddns#-deploy-with-docker-compose) - - πŸ‹ [Kubernetes](https://github.com/timothymiller/cloudflare-ddns#-kubernetes) - - 🐧 [Bare Metal (Crontab)](https://github.com/timothymiller/cloudflare-ddns#-deploy-with-linux--cron) -- [Building from source](https://github.com/timothymiller/cloudflare-ddns#building-from-source) -- [License](https://github.com/timothymiller/cloudflare-ddns#license) -- [Author](https://github.com/timothymiller/cloudflare-ddns#author) +## πŸ’― Complete Support of Domain Names, Subdomains, and IPv4 & IPv6 -## πŸ‡ΊπŸ‡Έ Origin - -This script was written for the Raspberry Pi platform to enable low cost self hosting to promote a more decentralized internet. - -### 🧹 Safe for use with existing records - -`cloudflare-ddns` handles the busy work for you, so deploying web apps is less of a clickfest. Every 5 minutes, the script fetches public IPv4 and IPv6 addresses and then creates/updates DNS records for each subdomain in Cloudflare. - -#### Optional features - -Stale, duplicate DNS records are removed for housekeeping. +- 🌐 Supports multiple domains (zones) on the same IP. +- πŸ“  Supports multiple subdomains on the same IP. +- πŸ“‘ IPv4 and IPv6 support. +- 🌍 Supports all Cloudflare regions. +- πŸ‡ΊπŸ‡Έ Made in the U.S.A. ## πŸ“Š Stats @@ -59,19 +44,6 @@ Stale, duplicate DNS records are removed for housekeeping. [πŸ‘‰ Click here to buy a domain name](https://namecheap.pxf.io/e47gjr) and [get a free Cloudflare account](https://developers.cloudflare.com/fundamentals/account-and-billing/account-setup/create-account/). -### Supported Platforms - -- [Docker](https://docs.docker.com/get-docker/) -- [Docker Compose](https://docs.docker.com/compose/install/) (optional) -- [Kubernetes](https://kubernetes.io/docs/tasks/tools/) (optional) -- [Python 3](https://www.python.org/downloads/) (optional) - -### Helpful links - -- [Cloudflare API token](https://dash.cloudflare.com/profile/api-tokens) -- [Cloudflare zone ID](https://support.cloudflare.com/hc/en-us/articles/200167836-Where-do-I-find-my-Cloudflare-IP-address-) -- [Cloudflare zone DNS record ID](https://support.cloudflare.com/hc/en-us/articles/360019093151-Managing-DNS-records-in-Cloudflare) - ## 🚦 Getting Started First copy the example configuration file into the real one. @@ -122,16 +94,61 @@ Some ISP provided modems only allow port forwarding over IPv4 or IPv6. In this c ## πŸ“  Hosting multiple subdomains on the same IP? -You can save yourself some trouble when hosting multiple domains pointing to the same IP address (in the case of Traefik) by defining one A & AAAA record 'ddns.example.com' pointing to the IP of the server that will be updated by this DDNS script. For each subdomain, create a CNAME record pointing to 'ddns.example.com'. Now you don't have to manually modify the script config every time you add a new subdomain to your site! +This script can be used to update multiple subdomains on the same IP address. -## 🌐 Hosting multiple domains (zones) on the same IP? - -You can handle ddns for multiple domains (cloudflare zones) using the same docker container by separating your configs inside `config.json` like below: +For example, if you have a domain `example.com` and you want to host additional subdomains at `foo.example.com` and `bar.example.com` on the same IP address, you can use this script to update the DNS records for all subdomains. ### ⚠️ Note +Please remove the comments after `//` in the below example. They are only there to explain the config. + Do not include the base domain name in your `subdomains` config. Do not use the [FQDN](https://en.wikipedia.org/wiki/Fully_qualified_domain_name). +### πŸ‘‰ Example πŸš€ + +```bash +{ + "cloudflare": [ + { + "authentication": { + "api_token": "api_token_here", // Either api_token or api_key + "api_key": { + "api_key": "api_key_here", + "account_email": "your_email_here" + } + }, + "zone_id": "your_zone_id_here", + "subdomains": [ + { + "name": "", // Root domain (example.com) + "proxied": true + }, + { + "name": "foo", // (foo.example.com) + "proxied": true + }, + { + "name": "bar", // (bar.example.com) + "proxied": true + } + ] + } + ], + "a": true, + "aaaa": true, + "purgeUnknownRecords": false, + "ttl": 300 +} +``` + +## 🌐 Hosting multiple domains (zones) on the same IP? + +You can handle ddns for multiple domains (cloudflare zones) using the same docker container by duplicating your configs inside the `cloudflare: []` key within `config.json` like below: + +### ⚠️ Note: + +If you are using API Tokens, make sure the token used supports editing your zone ID. + ```bash { "cloudflare": [ @@ -143,7 +160,27 @@ Do not include the base domain name in your `subdomains` config. Do not use the "account_email": "your_email_here" } }, - "zone_id": "your_zone_id_here", + "zone_id": "your_first_zone_id_here", + "subdomains": [ + { + "name": "", + "proxied": false + }, + { + "name": "remove_or_replace_with_your_subdomain", + "proxied": false + } + ] + }, + { + "authentication": { + "api_token": "api_token_here", + "api_key": { + "api_key": "api_key_here", + "account_email": "your_email_here" + } + }, + "zone_id": "your_second_zone_id_here", "subdomains": [ { "name": "", @@ -162,6 +199,10 @@ Do not include the base domain name in your `subdomains` config. Do not use the } ``` +### 🧹 Optional features + +`purgeUnknownRecords` removes stale DNS records from Cloudflare. This is useful if you have a dynamic DNS record that you no longer want to use. + ### πŸ—£οΈ Call to action: Docker environment variable support I am looking for help adding Docker environment variable support to this project. If interested, check out [this comment](https://github.com/timothymiller/cloudflare-ddns/pull/35#issuecomment-974752476) and open a PR. @@ -173,7 +214,7 @@ Pre-compiled images are available via [the official docker container on DockerHu Modify the host file path of config.json inside the volumes section of docker-compose.yml. ```yml -version: '3.7' +version: '3.9' services: cloudflare-ddns: image: timothyjmiller/cloudflare-ddns:latest @@ -300,6 +341,19 @@ Recommended for production docker run -d timothyjmiller/cloudflare_ddns:latest ``` +## Supported Platforms + +- [Docker](https://docs.docker.com/get-docker/) +- [Docker Compose](https://docs.docker.com/compose/install/) (optional) +- [Kubernetes](https://kubernetes.io/docs/tasks/tools/) (optional) +- [Python 3](https://www.python.org/downloads/) (optional) + +## πŸ“œ Helpful links + +- [Cloudflare API token](https://dash.cloudflare.com/profile/api-tokens) +- [Cloudflare zone ID](https://support.cloudflare.com/hc/en-us/articles/200167836-Where-do-I-find-my-Cloudflare-IP-address-) +- [Cloudflare zone DNS record ID](https://support.cloudflare.com/hc/en-us/articles/360019093151-Managing-DNS-records-in-Cloudflare) + ## License This Template is licensed under the GNU General Public License, version 3 (GPLv3).