mirror of https://github.com/YuzuZensai/Cloudflare-DDNS-Updater.git synced 2026-07-29 17:00:56 +00:00

Files

T

NukoDesuuandGitHub 22dc5d8b5f Update README and add Docker Compose example (#2 )

* 📃 docs: readme by AI

* 📦 build: docker compose and env example

2026-07-01 03:38:51 +07:00

5.9 KiB

Raw Blame History

Cloudflare DDNS Updater

Cloudflare DDNS Updater keeps Cloudflare DNS records pointed at the machine's current public IPv4 and/or IPv6 address.

The container reads:

Environment variables from Docker, usually via --env-file .env.
DNS update rules from /home/node/app/configs/UpdaterConfig.json inside the container.

Quick Start

Pull the published image:

docker pull ghcr.io/yuzuzensai/cloudflare-ddns-updater:latest

Create .env from the example:

cp .env.example .env

Edit .env and set your Cloudflare API token:

NODE_ENV=production
EXAMPLE_SITE_TOKEN=replace-with-cloudflare-api-token

Create configs/UpdaterConfig.json:

[
  {
    "token": "{ENV_TOKEN:EXAMPLE_SITE_TOKEN}",
    "updateInterval": 60,
    "zone": [
      {
        "id": "cloudflare-zone-id",
        "type": "A",
        "name": "example.com",
        "content": "{CURRENT_IPv4}",
        "ttl": 1,
        "proxied": false
      },
      {
        "id": "cloudflare-zone-id",
        "type": "AAAA",
        "name": "example.com",
        "content": "{CURRENT_IPv6}",
        "ttl": 1,
        "proxied": false
      }
    ]
  }
]

Run the container:

docker run -d \
  --name cloudflare-ddns-updater \
  --restart unless-stopped \
  --env-file .env \
  -v "$(pwd)/configs:/home/node/app/configs" \
  ghcr.io/yuzuzensai/cloudflare-ddns-updater:latest

View logs:

docker logs -f cloudflare-ddns-updater

Docker Compose

services:
  cloudflare-ddns-updater:
    image: ghcr.io/yuzuzensai/cloudflare-ddns-updater:latest
    container_name: cloudflare-ddns-updater
    restart: unless-stopped
    env_file:
      - .env
    volumes:
      - ./configs:/home/node/app/configs

Start it with:

docker compose up -d

Configuration

configs/UpdaterConfig.json is an array of Cloudflare account/token configurations.

Each top-level object uses these fields:

token: Cloudflare API token, or an environment reference like {ENV_TOKEN:EXAMPLE_SITE_TOKEN}.
updateInterval: update interval in seconds.
zone: DNS records to manage.

Each zone entry uses these fields:

id: Cloudflare zone ID.
type: DNS record type, usually A or AAAA.
name: DNS record name, for example example.com or home.example.com.
content: {CURRENT_IPv4} for an A record or {CURRENT_IPv6} for an AAAA record.
ttl: Cloudflare TTL. Use 1 for automatic TTL.
proxied: Cloudflare proxy status, true or false.

Important: keep the JSON property order shown in the examples. The current config validator expects exact key order.

Cloudflare Zone ID And Token

You need two Cloudflare values before running the updater:

Zone ID: identifies the Cloudflare zone/domain that contains the DNS records.
API token: authorizes the updater to read and edit DNS records in that zone.

The Zone ID goes in configs/UpdaterConfig.json as zone[].id.

The API token should go in .env, then configs/UpdaterConfig.json references it with {ENV_TOKEN:VARIABLE_NAME}. The variable name is up to you. EXAMPLE_SITE_TOKEN, HOME_SITE_TOKEN, MY_DOMAIN_TOKEN, or any other valid environment variable name will work as long as both files use the same name.

Get Your Zone ID

Log in to the Cloudflare dashboard.
Select the domain you want to update.
Open the domain overview page.
Find Zone ID in the right sidebar under API.
Copy that value into each matching zone[].id field in configs/UpdaterConfig.json.

Example:

{
  "id": "023e105f4ecef8ad9ca31a8372d0c353",
  "type": "A",
  "name": "home.example.com",
  "content": "{CURRENT_IPv4}",
  "ttl": 1,
  "proxied": false
}

Create an API Token

Log in to the Cloudflare dashboard.
Click your profile icon in the top-right corner.
Open My Profile.
Open API Tokens.
Select Create Token.

The easiest option is the built-in template:

Find the Edit zone DNS template.
Select Use template.
Under Zone Resources, select Include > Specific zone > your domain.
Leave the permissions as DNS edit/read permissions.
Select Continue to summary.
Review the token summary.
Select Create Token.
Copy the token immediately. Cloudflare only shows it once.

If you create a custom token instead, use this setup:

Select Create Custom Token.
Give it a clear name, for example Cloudflare DDNS Updater.
Add these permissions:

Zone > DNS > Edit
Zone > Zone > Read

Set the zone resource scope:

Under Zone Resources, choose Include.
Choose Specific zone.
Select the domain this updater will manage.
Select Continue to summary.
Review the token summary.
Select Create Token.
Copy the token immediately. Cloudflare only shows it once.

Do not use your Global API Key. This app only needs a scoped API token with DNS access for the selected zone.

After creating the token, copy it into .env. The name before = is the environment variable name. You can change it.

EXAMPLE_SITE_TOKEN=your-cloudflare-api-token

If you change the variable name in .env, update the token value in configs/UpdaterConfig.json to match it exactly.