Cloudflare DDNS

A lightweight dynamic DNS updater for Cloudflare, written in TypeScript with Bun. Automatically updates your DNS records when your public IP changes.

Features

• Tiny footprint - Only 12MB RAM usage
• Fast startup - Compiled to bytecode for instant launches
• Multiple records - Update multiple DNS records with a single instance
• Dual fallback - Uses both ipify.org and AWS CheckIP for reliability
• Secure - Runs on distroless base with no shell or package manager

Quick Start

Using Docker (Recommended)

docker run -d \
  -e CF_AUTH_EMAIL=your@email.com \
  -e CF_AUTH_KEY=your-cloudflare-api-key \
  -e CF_RECORDS=zone_id:example.com:true \
  cloudflare-ddns:latest

Or use an environment file:

cp .env.sample .env
# Edit .env with your details
docker run -d --env-file .env cloudflare-ddns:latest

Running Locally

bun install
cp .env.sample .env
# Edit .env with your credentials
bun run index.ts

Configuration

Set these environment variables:

• CF_AUTH_EMAIL - Your Cloudflare account email
• CF_AUTH_KEY - Your Cloudflare API key (not token)
• CF_RECORDS - DNS records to update

Record Format

Records use the format zone_id:record_name:proxy, separated by commas for multiple records:

# Single record with proxy enabled
CF_RECORDS=abc123:example.com:true

# Multiple records, mixed proxy settings
CF_RECORDS=abc123:example.com:true,def456:subdomain.example.com:false,ghi789:api.example.com:false

• zone_id - Found in your Cloudflare domain's Overview page
• record_name - The DNS record to update (e.g., example.com)
• proxy - true to proxy through Cloudflare, false for DNS-only

How It Works

The service checks your public IP every 10 seconds. When it changes, it updates your Cloudflare DNS records automatically. Every 5 minutes, it syncs with Cloudflare to ensure everything stays in sync.

Building

# Build Docker image
docker build -t cloudflare-ddns .

# Compile standalone binary
bun build --compile --minify --bytecode --sourcemap ./index.ts --outfile cloudflare-ddns

Testing

bun test

License

MIT