Cloudflare DDNS

Holden can automatically create and update Cloudflare DNS records for your apps. When a container with a domain: starts, its domain gets pointed to your server’s public IP — no manual DNS management needed.

This is handled by a lightweight sidecar container (holden-ddns) that watches Docker labels and syncs them to Cloudflare.

How It Works

1. The sidecar reads holden.domains labels from all running containers via the Docker socket
2. It detects your server’s public IP
3. For each domain, it finds the matching Cloudflare zone and creates or updates an A record
4. It reacts to container start/stop events and periodically checks for IP changes

flowchart LR
    D[Docker socket] -->|read labels| S[holden-ddns]
    S -->|detect IP| IP[Public IP]
    S -->|update records| CF[Cloudflare API]

Setup

Set CLOUDFLARE_API_TOKEN on the Holden container. When present, Holden spawns the holden-ddns sidecar automatically. Remove the variable to disable DDNS.

Creating an API Token

1. Go to Cloudflare API Tokens
2. Click Create Token
3. Use the Edit zone DNS template, or create a custom token with:
   • Zone > Zone > Read — to list your zones
   • Zone > DNS > Edit — to create and update records
4. Set the zone scope to All zones (or limit to specific zones)

Caution

Use an API Token, not a Global API Key. API Tokens are scoped to specific permissions and can be revoked independently.

Configuration Reference All DDNS environment variables: CLOUDFLARE_API_TOKEN, CLOUDFLARE_DDNS_FORCE, CLOUDFLARE_DDNS_PROXIED

Per-Service Proxy Override

Note

The DDNS sidecar supports a holden.cf.proxy label to override the global proxy setting per container. A cf_proxy option in holden.yml to control this is planned but not yet implemented — for now, CLOUDFLARE_DDNS_PROXIED applies to all domains.

The holden.domains Label

Holden sets a holden.domains label on every container that has a domain: configured:

holden.domains: "app.example.com,www.example.com"

This is a comma-separated list of all domains for that service. The DDNS sidecar reads this label — it never parses Traefik rules or reads your holden.yml files.

The Overseer also sets holden.domains on the Holden container itself when HOLDEN_PUBLIC_DOMAIN is configured, so the dashboard/webhook domain gets DNS records too.

Record Management

The sidecar adds a comment to every DNS record it creates:

managed by holden

Update Behavior

Record exists?	Comment	FORCE off	FORCE on
No	—	Creates record	Creates record
Yes, wrong IP	managed by holden	Updates record	Updates record
Yes, wrong IP	Other / none	Skips	Updates record
Yes, correct IP	—	No-op	No-op

Without FORCE, the sidecar only touches records it created. This prevents accidentally overwriting records managed by other tools or set manually.

Removed Domains

When a domain is removed from your config (or an app is deleted), the DNS record is not automatically deleted or modified. It continues pointing at your server’s IP, where Traefik will return a 404. Clean up stale records manually in the Cloudflare dashboard when you’re ready.

Event-Driven Updates

The sidecar subscribes to Docker container events (start, stop, die). When a Holden-managed container changes, it re-scans all labels and syncs. This means DNS updates happen within seconds of a deployment.

A periodic fallback (every 5 minutes) catches IP changes that happen without container events — for example, if your ISP assigns a new IP.

Configuration Reference All Holden environment variables including DDNS settings