Updated README.md
This commit is contained in:
Timothy Miller
parent
2ad7e57d65
commit
7212161f7b
150
README.md
150
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).
|
||||
|
||||
Reference in New Issue
Block a user