How to Set Up Free Dynamic DNS (DDNS) with Cloudflare (Docker, Debian, or Windows)

If you host home services—like a Plex server, Home Assistant, WireGuard VPN, or web apps—you’ve likely run into the dynamic IP problem: your Internet Service Provider (ISP) periodically changes your home public IP address, breaking your remote connection.

While paid services like DynDNS or No-IP exist, you can build a faster, more secure, and completely custom solution for free using Cloudflare and a domain name you control.

In this guide, we'll walk step-by-step through setting up Dynamic DNS (DDNS) with Cloudflare using three flexible deployment options: Docker, Debian Linux, or Windows.

Step 1: Set Up Your Domain and Initial DNS Record

Before automating your IP updates, you need a domain pointed to Cloudflare and a base record for the script to manage.

  1. Add Your Domain to Cloudflare:
    • Sign in to the Cloudflare Dashboard and click Add a Site.
    • Change your domain’s nameservers at your registrar (Namecheap, GoDaddy, Google Domains, etc.) to the nameservers Cloudflare assigns to you.
  2. Create a Placeholder A Record:
    • Go to DNS > Records inside your Cloudflare dashboard and click Add Record.
    • Type: A
    • Name: home (or @ for your root domain, or any subdomain of your choice).
    • IPv4 address: Enter a placeholder IP like 1.1.1.1 (our updater script will fix this shortly).
    • Proxy status:
      • Proxied (Orange Cloud): Best for web apps. Hides your public IP and routes traffic through Cloudflare's security layer (HTTP/HTTPS only).
      • DNS Only (Grey Cloud): Best for non-HTTP services like SSH, VPNs, or gaming servers, as it exposes your raw public IP directly.
    • TTL: Auto
    • Click Save.

Step 2: Create a Scoped API Token

Never use your account's Global API Key for routine automation scripts. Instead, create a restricted token that can only modify the specific DNS zone you select.

  1. In Cloudflare, click your Profile Icon (top right) > Profile.
  2. Select API Tokens from the left navigation panel, then click Create Token.
  3. Locate the Edit zone DNS template and click Use template.
  4. Adjust the scope under Permissions:
    • Zone | DNS | Edit
  5. Adjust Zone Resources:
    • Include | Specific zone | Select your target domain
  6. Click Continue to summary > Create Token.
  7. Copy your API token immediately and store it in a password manager. Cloudflare will not display it again.

Step 3: Configure Your DDNS Updater

Choose the method below that best fits your home network setup.

Option A: Docker (Recommended for Containerized Environments)

If you run Docker or Unraid, using the popular favonia/cloudflare-ddns image is the cleanest, zero-maintenance method.

  1. Create or open your docker-compose.yml file:
version: '3.8'
services:
  cloudflare-ddns:
    image: favonia/cloudflare-ddns:latest
    container_name: cloudflare-ddns
    network_mode: host
    environment:
      - API_KEY=YOUR_CLOUDFLARE_API_TOKEN
      - DOMAINS=home.example.com
      - UPDATE_CRON=@every 5m
    restart: unless-stopped
  1. Start the container in the background:
docker compose up -d

Option B: Native ddclient on Debian / Ubuntu Linux

If you run a lightweight Debian or Ubuntu server, ddclient provides a native Linux service that runs smoothly in the background.

  1. Install ddclient: 
    sudo apt update
sudo apt install ddclient libdata-validate-ip-perl -y
  2. Configure the Service:
    Open the configuration file: 
    sudo nano /etc/ddclient.conf
    Replace its entire contents with the following: 
    # /etc/ddclient.conf
daemon=300
syslog=yes
pid=/var/run/ddclient.pid
ssl=yes
use=web, web=ipify-ipv4

protocol=cloudflare
zone=example.com
login=token
password=YOUR_CLOUDFLARE_API_TOKEN
home.example.com
  3. Secure File Permissions and Restart: 
    sudo chmod 600 /etc/ddclient.conf
sudo systemctl restart ddclient
sudo systemctl enable ddclient

Option C: Windows Background Task (Cloudflare-DDNS-CLI)

If your main server or Always-On node runs on Windows, you can automate updates cleanly without needing Linux subsystems or complex PowerShell scripting.

  1. Download: Grab the latest Windows zip release (cloudflare-ddns-windows-amd64.zip) from the Cloudflare-DDNS-CLI GitHub Releases.
  2. Extract: Place the files in a permanent directory (e.g., C:\Program Files\Cloudflare-DDNS\).
  3. Configure: In that folder, create a file named config.json: 
    {
  "cloudflare": [
    {
      "authentication": {
        "api_token": "YOUR_CLOUDFLARE_API_TOKEN"
      },
      "zone_id": "YOUR_CLOUDFLARE_ZONE_ID",
      "subdomains": [
        {
          "name": "home",
          "proxied": false
        }
      ]
    }
  ],
  "a": true,
  "aaaa": false,
  "purgeUnknownRecords": false,
  "ttl": 300
}

    (Note: Find your Zone ID on the right sidebar of your Cloudflare Domain Overview tab).

  4. Automate with Windows Task Scheduler:
    • Search Windows for Task Scheduler and select Create Basic Task.
    • Name: Cloudflare DDNS Updater.
    • Set Trigger to When the computer starts (or set a daily schedule that repeats every 5 to 10 minutes under Advanced Settings).
    • Action: Start a program > Browse to cloudflare-ddns.exe.
    • Enable Run whether user is logged on or not under General Settings.

Step 4: Verification

To verify that your automation works:

  1. Trigger a run manually or wait 5 minutes for your chosen background process to run.
  2. Return to your Cloudflare DNS Dashboard.
  3. Check your A record—the placeholder IP (1.1.1.1) should now be updated to your actual home network's public IP address.

Enjoy seamless, free remote access to your home network without paying for dynamic DNS services!

Picture of Joseph Galea

Joseph Galea