Ecosyste.ms: Awesome
An open API service indexing awesome lists of open source software.
https://github.com/andcool-systems/ddns-js
Implementation a DDNS via CloudFlare API
https://github.com/andcool-systems/ddns-js
cloudflare ddns ddns-updater nodejs typescript
Last synced: 6 days ago
JSON representation
Implementation a DDNS via CloudFlare API
- Host: GitHub
- URL: https://github.com/andcool-systems/ddns-js
- Owner: Andcool-Systems
- Created: 2024-09-10T18:30:44.000Z (5 months ago)
- Default Branch: main
- Last Pushed: 2025-01-06T18:03:38.000Z (about 1 month ago)
- Last Synced: 2025-01-31T11:35:51.361Z (11 days ago)
- Topics: cloudflare, ddns, ddns-updater, nodejs, typescript
- Language: TypeScript
- Homepage:
- Size: 17.6 KB
- Stars: 2
- Watchers: 1
- Forks: 0
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
Awesome Lists containing this project
README
# 🌐 DDNS over CloudFlare
> [!TIP]
> **Dynamic Domain Name System (DDNS)** is a mechanism for automatically updating DNS records for domain names whenever the IP address changes.
**When is DDNS useful?**
- If you have a **public IP address** that changes periodically.
- When you need to access your device from the internet using a stable domain name.
- In cases where your internet provider assigns dynamic IP addresses.
---
## ✨ Features
- 📡 **Automatic IP Update** — Automatically tracks changes to your IP address and updates DNS records.
- 🔐 **Security** — Uses a CloudFlare token with minimal required access permissions.
- ⏱️ **Flexible Check Intervals** — Configurable frequency for checking IP addresses.
- 📋 **Multiple Record Support** — Allows monitoring and updating multiple DNS records simultaneously.
- 🐳 **Docker Compatibility** — Easy deployment via Docker Compose.
- 🌐 **IP Address Detection** — Uses the [cdn-cgi/trace](https://www.cloudflare.com/cdn-cgi/trace) service to determine the current IP address.
---
## 🛠️ Configuration — `config.yaml`
To run the project, a configuration file `config.yaml` must be located in the root directory. Example:
```yaml
zone:
period: 30
token:
records:
- hostname: example.com
proxied: false
- hostname: test.example.com
proxied: true
```
### Parameters:
- **`zone`** – CloudFlare zone ID.
- **`period`** – Interval (in seconds) for checking the current IP address *(recommended: 30 seconds)*.
- **`token`** – Bearer [CloudFlare token](https://dash.cloudflare.com/profile/api-tokens) with permissions to read and modify DNS records.
- **`records`** – List of DNS records for monitoring and updating:
- **`hostname`** – DNS record name.
- **`proxied`** – Enables (true) or disables (false) proxying through CloudFlare.
---
## 🚀 Getting Started
### Run via Docker Compose:
```bash
docker compose up -d
```
### Standard TypeScript Run:
1. Install dependencies:
```bash
npm install
```
2. Compile TypeScript code:
```bash
npm run build
```
3. Start the project:
```bash
npm run start
```
---
## ⚙️ How It Works
1. On startup, the application checks for DNS records in CloudFlare based on the parameters in `config.yaml`.
2. If a record is missing, it creates one with the current IP address.
3. The program enters an infinite loop, checking the IP address every `period` seconds:
- Checks the current IP address.
- Updates it in CloudFlare if it has changed.
> [!TIP]
> It is recommended to set the check interval to at least 30 seconds to avoid excessive requests to the CloudFlare API.
---
Created with ❤ by AndcoolSystems — *September 10, 2024.*