Deploy and Usage Guide: favonia/cloudflare-ddns

1. Prerequisites

Go 1.21 or later: Required to build the project from source. Check with go version.
Cloudflare account: You need an active Cloudflare account with domains configured.
Cloudflare API Token: A token with specific permissions (detailed in Configuration).
Git: To clone the repository.
Optional: make for using the provided Makefile (not strictly required).

2. Installation

From Source

Clone the repository and build the binary:

git clone https://github.com/favonia/cloudflare-ddns.git
cd cloudflare-ddns
go build -o cloudflare-ddns ./cmd/cloudflare-ddns

This creates a standalone cloudflare-ddns binary in the current directory.

Using `go install`

For a system-wide installation:

go install github.com/favonia/cloudflare-ddns/cmd/cloudflare-ddns@latest

The binary will be placed in your $GOPATH/bin (usually ~/go/bin).

Pre-built Binaries

Check the GitHub Releases page for pre-compiled binaries for various platforms.

3. Configuration

Configuration is done entirely through environment variables.

Essential Variables

CF_API_TOKEN: Your Cloudflare API token. Required.
CF_ACCOUNT_ID: Your Cloudflare Account ID. Required.
DOMAINS: Comma-separated list of domains to update (e.g., example.com,sub.example.com). Required.

API Token Permissions

Your CF_API_TOKEN must have these permissions:

Zone - DNS: Edit (For updating DNS records)
Account - Account Filter Lists: Edit (If using WAF list features. The updater will hint if this is missing: "Double check your API token and account ID. Make sure you granted the 'Edit' permission of 'Account - Account Filter Lists'")

Optional Variables

IP4_PROVIDER / IP6_PROVIDER: IP detection service (e.g., cloudflare, local, url:...). Defaults: cloudflare for both.
IP4_POLICY / IP6_POLICY: Update policy (cloudflare.update, waf.update, etc.).
TTL: DNS record TTL in seconds (1 = automatic). Default: 1.
PROXIED: Whether to proxy through Cloudflare (true/false). Default: false.
DELETE_ON_STOP: Delete DNS records on shutdown (true/false). Default: false.
WAF_LIST_DESCRIPTION: Description for WAF lists. Default: "Managed by cloudflare-ddns".
UPDATE_CRON: Cron schedule for updates. Default: "@every 5m".
UPDATE_ON_START: Update immediately on start (true/false). Default: true.

Example `.env` file

CF_API_TOKEN=your_token_here
CF_ACCOUNT_ID=your_account_id_here
DOMAINS=example.com,home.example.com
PROXIED=true
UPDATE_CRON="@every 10m"

4. Build & Run

Development Build

# Build with debug symbols
go build -gcflags="all=-N -l" -o cloudflare-ddns ./cmd/cloudflare-ddns

# Run tests
go test ./...

Production Run

Set environment variables:

export CF_API_TOKEN="your_token"
export CF_ACCOUNT_ID="your_account_id"
export DOMAINS="example.com"

Run the binary:
```
./cloudflare-ddns
```
For continuous operation, use the built-in cron scheduler (configured via UPDATE_CRON).

Docker

A Docker image is available:

docker run -e CF_API_TOKEN -e CF_ACCOUNT_ID -e DOMAINS favonia/cloudflare-ddns

Or build locally:

docker build -t cloudflare-ddns .
docker run --env-file .env cloudflare-ddns

5. Deployment

Suitable Platforms

Linux servers/VPS: Run as a systemd service for reliability.
Docker containers: Deploy on any container platform (Docker, Kubernetes, Podman).
Cloud VMs: AWS EC2, Google Compute Engine, Azure VMs.
Raspberry Pi/Home Server: Ideal for personal dynamic DNS.
CI/CD pipelines: Run as a step to update DNS during deployments.

Systemd Service (Linux)

Create /etc/systemd/system/cloudflare-ddns.service:

[Unit]
Description=Cloudflare DDNS Updater
After=network.target

[Service]
Type=simple
User=ddns
EnvironmentFile=/etc/cloudflare-ddns/env
ExecStart=/usr/local/bin/cloudflare-ddns
Restart=on-failure
RestartSec=30

[Install]
WantedBy=multi-user.target

Then:

sudo systemctl daemon-reload
sudo systemctl enable --now cloudflare-ddns

Docker Compose

version: '3'
services:
  cloudflare-ddns:
    image: favonia/cloudflare-ddns:latest
    container_name: cloudflare-ddns
    env_file:
      - .env
    restart: unless-stopped

6. Troubleshooting

Permission Errors

"Double check your API token": Ensure your CF_API_TOKEN has the correct permissions (Zone - DNS: Edit).
WAF list permission errors: If using WAF features, grant "Account - Account Filter Lists: Edit" permission.

TTL/Proxy Mismatch Warnings

The updater checks for configuration consistency. If you see:

⚠ The TTL for the A record of example.com (ID: ...) is 300. However, it is expected to be 120.

Either:

Update the TTL in Cloudflare Dashboard to match TTL environment variable, OR
Change TTL environment variable to match the current setting.

Similar warnings appear for proxy status mismatches.

No IP Address Found

Check IP4_PROVIDER/IP6_PROVIDER settings.
Ensure your network has the appropriate IP version connectivity.
For custom providers using url:..., verify the endpoint returns a plain IP.

WAF List Description Mismatch

If you see:

⚠ The description for the list ... is "Old description". However, its description is expected to be "Managed by cloudflare-ddns".