How timothymiller/cloudflare-ddns works
Project type and purpose
• This is a small self-hosted Python service (“cloudflare-ddns.py”) that periodically reads a JSON configuration, checks your public IPv4/IPv6 addresses, and updates DNS records in Cloudflare via its HTTP API.
• It’s designed to run in various environments (bare-metal with cron or systemd, Docker container, Docker Compose, or Kubernetes).
File structure
• Top-level
• cloudflare-ddns.py: main application script
• config-example.json: sample user configuration
• requirements.txt: Python dependencies (zero-dependency, likely only standard library / HTTP client)
• start-sync.sh: bootstraps a Python venv and runs the script
• Dockerfile: builds a minimal container image
• Deployment folders
• docker/: docker-compose.yml for single-host Docker Compose
• k8s/: Kubernetes Deployment / Secret template
• systemd/: .service and .timer files for systemd scheduling
• scripts/: helper scripts for building, publishing, and running Docker images
• GitHub CI/CD workflows under .github/workflows/image.yml, plus issue templates and Dependabot config
README
• Describes feature set (IPv4/IPv6, subdomains, load-balancing, caching)
• Explains configuration schema for zones, authentication, TTL, purge options
• Shows four run-modes:
a. Linux + cron (via start-sync.sh)
b. systemd + timer
c. Docker / Docker Compose
d. Kubernetes (Secret + Deployment)
• Mentions environment variable support and multi-arch Docker builds
a. Main components
• Scheduler / Runner (cron job, systemd timer, or k8s CronJob / Deployment with built-in loop)
• Python Runtime (cloudflare-ddns.py inside a venv or container)
• Configuration Store (config.json mounted as a file or provided as a Kubernetes Secret)
• Local Cache (in-memory or file cache of recent API responses)
• Cloudflare API (external HTTP service)
• (Optional) Docker Host or Kubernetes Cluster orchestrator
b. Relationships and interactions
1. Scheduler triggers the Python script at configured intervals
2. Script loads config.json / environment variables
3. Script reads current public IP(s) via local interface or external endpoint (e.g., cdn-cgi/trace)
4. Script compares against cached value; if changed or purgeUnknownRecords=true, it issues HTTP requests to Cloudflare API to update DNS records
5. Cloudflare API responds; script updates cache
6. Logs or metrics can be emitted to stdout (Docker logs), systemd journal, or Kubernetes logs
c. Architectural patterns / design principles
• Single responsibility: one script does configuration parsing, caching, IP detection, API updates
• Config-driven behavior: all credentials, zones, subdomains, and TTLs defined in JSON or environment variables
• Adapter pattern: can run under different schedulers without changing core logic
• Zero-trust container: runs with host networking (in Docker), minimal privileges, file-based config or Kubernetes Secret
d. Key technologies and frameworks
• Python 3.5+ (stdlib HTTP or requests)
• Docker (small Alpine‐based image)
• Docker Compose (network_mode: host)
• Kubernetes Deployment & Secret
• systemd service & timer units
• Bash scripts for building and orchestrating
• Cloudflare HTTP REST API
Details
• Call out authentication flow: API token or API key + email → attached as HTTP header
• Polling interval (e.g., every 15 minutes via cron or timer)
• Optional load-balancing logic path if configured (creates CNAME pools via API)
• If desired, annotate the Dockerfile layer breakdown (base image, application layer, entrypoint)