Migrate to qmcgaw/ddns-updater v0.3.0

BREAKING CHANGE: Replace custom implementation with universal DDNS client - Replace custom Python implementation with qmcgaw/ddns-updater - Add Web UI for monitoring on port 8000 - Add support for 50+ DNS providers (not just Hetzner) - Add multi-domain support via JSON configuration - Add config.json.example for Hetzner setup - Update documentation with Web UI and new setup process - Remove custom Python code, Dockerfile, requirements.txt - Simplify deployment with established, production-ready solution Benefits: - Professional Web UI for status monitoring - Active community support - Flexibility for future provider changes - Well-tested, production-ready solution Co-Authored-By: Claude Sonnet 4.5 <noreply@anthropic.com>
Add DynDNS implementation v0.2.0
2026-02-16 22:28:56 +01:00 · 2026-02-16 22:21:54 +01:00
7 changed files with 462 additions and 29 deletions
--- a/.env.example
+++ b/.env.example
@ -0,0 +1,9 @@
+# DDNS-Updater Konfiguration
+
+# Update-Intervall (Standard: 5m)
+# Mögliche Werte: 30s, 1m, 5m, 10m, etc.
+PERIOD=5m
+
+# Log Level
+# Mögliche Werte: debug, info, warning, error
+LOG_LEVEL=info
--- a/.gitignore
+++ b/.gitignore
@ -1,6 +1,10 @@
 # Environment variables
 .env

+# DDNS-Updater data
+data/
+config.json
+
 # Python
 __pycache__/
 *.py[cod]
@ -36,6 +40,7 @@ venv.bak/
 *.swp
 *.swo
 *~
+.claude/

 # Logs
 *.log
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@ -4,6 +4,55 @@ Alle wichtigen Änderungen an diesem Projekt werden in dieser Datei dokumentiert

 Das Format basiert auf [Keep a Changelog](https://keepachangelog.com/de/1.0.0/).

+## [0.3.0] - 2026-02-16
+
+### Geändert
+- **BREAKING**: Migration von eigener Implementierung zu **qmcgaw/ddns-updater**
+- Neue Konfiguration via JSON (`data/config.json`) statt Umgebungsvariablen
+- Vereinfachtes Setup mit etabliertem, universellen DDNS-Client
+
+### Hinzugefügt
+- Web-UI für Überwachung und Verwaltung (Port 8000)
+- Unterstützung für 50+ DNS-Provider (nicht nur Hetzner)
+- Multi-Domain-Support in einer Konfiguration
+- Beispiel-Konfiguration (`config.json.example`)
+- Verbesserte Dokumentation mit Web-UI Hinweisen
+
+### Entfernt
+- Eigene Python-Implementierung (`dyndns.py`)
+- Custom Dockerfile und requirements.txt
+- .dockerignore (nicht mehr benötigt)
+
+### Vorteile
+- Etablierte, gut getestete Lösung
+- Aktive Community und Support
+- Flexibilität für zukünftige Provider-Wechsel
+- Professionelle Web-UI zur Statusüberwachung
+
+## [0.2.0] - 2026-02-16
+
+### Hinzugefügt
+- Python-basierter DynDNS Client (`dyndns.py`)
+- Integration mit Hetzner DNS API v1
+- Automatische IP-Erkennung (IPv4/IPv6)
+- Automatische Zone-ID Ermittlung
+- Dockerfile mit Multi-Stage Build und Non-Root User
+- Docker Compose Konfiguration mit Restart-Policy
+- Umgebungsvariablen-Konfiguration über `.env`
+- Beispiel-Konfiguration (`.env.example`)
+- Python Dependencies (`requirements.txt`)
+- CLAUDE.md Entwicklerdokumentation
+- Logging mit konfigurierbarem Log-Level
+- Health Check für Container
+- .dockerignore für optimierte Builds
+
+### Features
+- Prüfung der IP-Änderung in konfigurierbaren Intervallen
+- Automatische Erstellung von DNS Records bei Bedarf
+- Automatische Aktualisierung bei IP-Änderung
+- Unterstützung für IPv4 (A) und IPv6 (AAAA) Records
+- Unterstützung für Root-Domain (@) und Subdomains
+
 ## [0.1.0] - 2026-02-16

 ### Hinzugefügt
--- a/CLAUDE.md
+++ b/CLAUDE.md
@ -0,0 +1,202 @@
+# CLAUDE.md
+
+This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
+
+## Project Overview
+
+This is a Docker-based Dynamic DNS client for Hetzner DNS (and 50+ other providers) using **[qmcgaw/ddns-updater](https://github.com/qdm12/ddns-updater)** - a universal, production-ready DDNS solution with web UI.
+
+**Core Components:**
+- `docker-compose.yml`: Service configuration using qmcgaw/ddns-updater image
+- `data/config.json`: DDNS configuration (domains, tokens, providers)
+- `config.json.example`: Configuration template for Hetzner setup
+
+## Development Commands
+
+### Docker Operations
+
+**Start the service:**
+```bash
+docker-compose up -d
+```
+
+**View logs:**
+```bash
+docker-compose logs -f
+```
+
+**Restart service:**
+```bash
+docker-compose restart
+```
+
+**Stop service:**
+```bash
+docker-compose down
+```
+
+**Check status:**
+```bash
+docker-compose ps
+```
+
+### Configuration Management
+
+**Create initial config:**
+```bash
+mkdir -p data
+cp config.json.example data/config.json
+# Edit data/config.json with your credentials
+```
+
+**Validate config JSON:**
+```bash
+cat data/config.json | jq .
+```
+
+**Get Hetzner Zone ID via API:**
+```bash
+curl -H "Auth-API-Token: YOUR_TOKEN" https://dns.hetzner.com/api/v1/zones
+```
+
+### Web UI
+
+**Access Web UI:**
+Open browser to `http://localhost:8000`
+
+The Web UI shows:
+- Current IP status
+- Last update timestamp
+- Update history
+- Errors and warnings
+- Per-domain status
+
+## Architecture
+
+### Application Flow
+
+1. **Initialization**: Load configuration from `data/config.json`
+2. **Main Loop**:
+   - Get current public IP (IPv4/IPv6)
+   - Compare with DNS records for each configured domain
+   - Update DNS if IP has changed
+   - Wait for configured period (default: 5 minutes)
+   - Repeat
+
+### Configuration Structure
+
+Configuration is in JSON format at `data/config.json`:
+
+```json
+{
+  "settings": [
+    {
+      "provider": "hetzner",
+      "zone_identifier": "zone_id",
+      "domain": "example.com",
+      "host": "@",
+      "ttl": 60,
+      "token": "api_token",
+      "ip_version": "ipv4"
+    }
+  ]
+}
+```
+
+**Key Parameters:**
+- `provider`: DNS provider name (hetzner, cloudflare, duckdns, etc.)
+- `zone_identifier`: Hetzner DNS Zone ID
+- `domain`: Base domain name
+- `host`: Subdomain or `@` for root
+- `ttl`: Time-to-live in seconds
+- `token`: Hetzner API token with DNS edit permissions
+- `ip_version`: `ipv4`, `ipv6`, or `ipv4 or ipv6`
+
+### Multi-Domain Support
+
+Add multiple entries in the `settings` array to manage multiple domains or subdomains.
+
+### Environment Variables
+
+Optional variables in `.env`:
+- `PERIOD`: Update check interval (default: 5m)
+- `LOG_LEVEL`: Logging verbosity (debug, info, warning, error)
+
+## Versioning Strategy
+
+This project uses a simplified versioning scheme:
+- **0.1**: Large changes (new features, breaking changes)
+- **0.0.1**: Small changes (bugfixes, minor improvements)
+- **1.x**: Major releases (only by explicit instruction)
+
+**When making changes:**
+1. Update `CHANGELOG.md` with the change description
+2. Increment version according to change size
+3. Work in feature branches, merge to main when ready
+
+## Key Files
+
+- `docker-compose.yml`: Service definition using qmcgaw/ddns-updater
+- `config.json.example`: Template for Hetzner configuration
+- `data/config.json`: Active configuration (not in git)
+- `.env.example`: Optional environment variables template
+- `CHANGELOG.md`: Version history
+
+## Security Notes
+
+- API token is sensitive - never commit `data/config.json` or `.env`
+- Container runs with minimal privileges
+- Only ports 8000 (web UI) exposed
+- Use HTTPS reverse proxy for production deployments
+- API token should have minimal required permissions (DNS read/write only)
+
+## Troubleshooting
+
+**View Web UI status:**
+```bash
+# Open http://localhost:8000 in browser
+```
+
+**Check container logs:**
+```bash
+docker-compose logs --tail=50 -f
+```
+
+**Validate configuration:**
+```bash
+# Check JSON syntax
+cat data/config.json | jq .
+```
+
+**Test API connectivity:**
+```bash
+# List zones
+curl -H "Auth-API-Token: YOUR_TOKEN" https://dns.hetzner.com/api/v1/zones
+
+# List records for a zone
+curl -H "Auth-API-Token: YOUR_TOKEN" "https://dns.hetzner.com/api/v1/records?zone_id=ZONE_ID"
+```
+
+**Debug mode:**
+Set `LOG_LEVEL=debug` in `.env` and restart container.
+
+**Container won't start:**
+- Check `docker-compose logs`
+- Verify `data/config.json` exists and is valid JSON
+- Check port 8000 is not in use
+
+## Provider Migration
+
+To switch from Hetzner to another provider:
+1. Check [supported providers](https://github.com/qdm12/ddns-updater#providers)
+2. Update `provider` field in `data/config.json`
+3. Adjust provider-specific fields
+4. Restart: `docker-compose restart`
+
+No code changes needed - just configuration!
+
+## Upstream Documentation
+
+- [DDNS-Updater GitHub](https://github.com/qdm12/ddns-updater)
+- [Hetzner Configuration Guide](https://github.com/qdm12/ddns-updater/blob/master/docs/hetzner.md)
+- [All Supported Providers](https://github.com/qdm12/ddns-updater#providers)
--- a/README.md
+++ b/README.md
@ -1,14 +1,18 @@
 # DynDNS Docker für Hetzner DNS

-Ein Docker-basiertes Dynamic DNS System für die Hetzner DNS Console.
+Ein Docker-basiertes Dynamic DNS System für die Hetzner DNS Console mit **[qmcgaw/ddns-updater](https://github.com/qdm12/ddns-updater)** - einem universellen DDNS-Client, der 50+ Provider unterstützt.

 ## Features

- Automatische Erkennung von IP-Änderungen
- Integration mit Hetzner DNS API
- Konfigurierbare Check-Intervalle
- Docker-Container für einfaches Deployment
- Umgebungsvariablen für sichere Konfiguration
+- ✅ Automatische Erkennung von IP-Änderungen
+- ✅ Integration mit Hetzner DNS API
+- ✅ Web-UI für Überwachung und Verwaltung (Port 8000)
+- ✅ Konfigurierbare Check-Intervalle
+- ✅ Unterstützt 50+ DNS-Provider (nicht nur Hetzner)
+- ✅ Multi-Domain-Support
+- ✅ IPv4 und IPv6 Unterstützung
+- ✅ Health Check für Container-Monitoring
+- ✅ Automatische Restart-Policy

 ## Voraussetzungen

@ -25,43 +29,125 @@ git clone <repository-url>
 cd dyndns-docker
 ```

-### 2. Konfiguration
+### 2. Konfiguration erstellen

-Kopieren Sie die Beispiel-Konfigurationsdatei und passen Sie sie an:
+#### a) Umgebungsvariablen (optional)

 ```bash
 cp .env.example .env
 ```

-Bearbeiten Sie die `.env` Datei mit Ihren Daten:
-
+Bearbeiten Sie `.env` für optionale Einstellungen:
 ```env
-HETZNER_API_TOKEN=your_api_token_here
-DOMAIN=example.com
-RECORD_NAME=home
-RECORD_TYPE=A
-CHECK_INTERVAL=300
+PERIOD=5m        # Update-Intervall
+LOG_LEVEL=info   # Log-Level
 ```

-### 3. Container starten
+#### b) DDNS-Konfiguration (erforderlich)
+
+Erstellen Sie `data/config.json` basierend auf der Vorlage:
+
+```bash
+mkdir -p data
+cp config.json.example data/config.json
+```
+
+Bearbeiten Sie `data/config.json`:
+
+```json
+{
+  "settings": [
+    {
+      "provider": "hetzner",
+      "zone_identifier": "your_zone_id_here",
+      "domain": "example.com",
+      "host": "@",
+      "ttl": 60,
+      "token": "your_hetzner_api_token_here",
+      "ip_version": "ipv4"
+    }
+  ]
+}
+```
+
+### 3. Hetzner API Token und Zone ID ermitteln
+
+#### API Token erstellen:
+1. Melden Sie sich im [Hetzner DNS Console](https://dns.hetzner.com/) an
+2. Gehen Sie zu **"API Tokens"**
+3. Klicken Sie auf **"Create access token"**
+4. Geben Sie einen Namen ein (z.B. "DynDNS")
+5. Wählen Sie **Read & Write** Rechte
+6. Kopieren Sie den generierten Token
+
+#### Zone ID finden:
+1. Gehen Sie zu Ihrer Domain-Übersicht
+2. Die **Zone ID** finden Sie in der URL oder im Domain-Detail
+3. Alternativ: API-Aufruf `curl -H "Auth-API-Token: YOUR_TOKEN" https://dns.hetzner.com/api/v1/zones`
+
+### 4. Container starten

 ```bash
 docker-compose up -d
 ```

+### 5. Web-UI aufrufen
+
+Öffnen Sie im Browser: **http://localhost:8000**
+
+Hier sehen Sie:
+- ✅ Aktuellen IP-Status
+- ✅ Letztes Update
+- ✅ Update-Historie
+- ✅ Fehler und Warnungen
+
 ## Konfiguration

+### Domain-Konfiguration
+
+| Parameter | Beschreibung | Beispiel |
+|-----------|-------------|----------|
+| `provider` | DNS-Provider Name | `hetzner` |
+| `zone_identifier` | Hetzner Zone ID | `abc123...` |
+| `domain` | Domain-Name | `example.com` |
+| `host` | Subdomain oder `@` für Root | `@`, `home`, `*.example.com` |
+| `ttl` | Time-to-Live in Sekunden | `60` |
+| `token` | Hetzner API Token | `xyz789...` |
+| `ip_version` | IP-Version | `ipv4`, `ipv6`, `ipv4 or ipv6` |
+
 ### Umgebungsvariablen

-| Variable | Beschreibung | Beispiel |
+| Variable | Beschreibung | Standard |
 |----------|-------------|----------|
-| `HETZNER_API_TOKEN` | Hetzner DNS API Token | `abc123...` |
-| `ZONE_ID` | Hetzner DNS Zone ID (optional, wird automatisch ermittelt) | `xyz789...` |
-| `DOMAIN` | Domain-Name | `example.com` |
-| `RECORD_NAME` | DNS Record Name | `home` oder `@` für Root |
-| `RECORD_TYPE` | DNS Record Typ | `A` (IPv4) oder `AAAA` (IPv6) |
-| `CHECK_INTERVAL` | Prüfintervall in Sekunden | `300` (5 Minuten) |
-| `LOG_LEVEL` | Log-Level | `INFO`, `DEBUG`, `WARNING` |
+| `PERIOD` | Update-Intervall | `5m` |
+| `LOG_LEVEL` | Log-Level | `info` |
+
+### Mehrere Domains konfigurieren
+
+Sie können mehrere Domains in `data/config.json` hinzufügen:
+
+```json
+{
+  "settings": [
+    {
+      "provider": "hetzner",
+      "zone_identifier": "zone1_id",
+      "domain": "example.com",
+      "host": "@",
+      "token": "token1",
+      "ip_version": "ipv4"
+    },
+    {
+      "provider": "hetzner",
+      "zone_identifier": "zone2_id",
+      "domain": "example.org",
+      "host": "home",
+      "token": "token2",
+      "ip_version": "ipv4"
+    }
+  ]
+}
+```

 ## Verwendung

@ -89,12 +175,49 @@ docker-compose restart
 docker-compose down
 ```

-## Hetzner DNS API Token erstellen
+### Konfiguration neu laden

-1. Melden Sie sich im [Hetzner DNS Console](https://dns.hetzner.com/) an
-2. Gehen Sie zu "API Tokens"
-3. Erstellen Sie einen neuen API Token mit Lese- und Schreibrechten
-4. Kopieren Sie den Token in Ihre `.env` Datei
+Nach Änderungen an `data/config.json`:
+
+```bash
+docker-compose restart
+```
+
+## Weitere unterstützte Provider
+
+Dieser Setup nutzt **qmcgaw/ddns-updater**, der auch diese Provider unterstützt:
+
+- Cloudflare
+- Google Domains
+- DuckDNS
+- No-IP
+- Namecheap
+- GoDaddy
+- **und 40+ weitere**
+
+Um einen anderen Provider zu nutzen, passen Sie einfach die `provider`-Konfiguration in `data/config.json` an. Siehe [Dokumentation](https://github.com/qdm12/ddns-updater) für Details.
+
+## Troubleshooting
+
+### Container startet nicht
+```bash
+docker-compose logs
+```
+
+### Web-UI nicht erreichbar
+- Prüfen Sie, ob Port 8000 verfügbar ist
+- Prüfen Sie Firewall-Einstellungen
+
+### DNS-Update schlägt fehl
+- Prüfen Sie den API Token
+- Prüfen Sie die Zone ID
+- Prüfen Sie die Logs: `docker-compose logs -f`
+
+### Konfiguration testen
+```bash
+# Prüfen Sie die config.json Syntax
+cat data/config.json | jq .
+```

 ## Versioning

@ -103,6 +226,12 @@ Dieses Projekt folgt einer vereinfachten Versionierungsstruktur:
 - **0.0.1**: Kleine Änderungen (Bugfixes, kleinere Verbesserungen)
 - **1.x**: Major Releases (nur nach Anweisung)

+## Links
+
+- [DDNS-Updater GitHub](https://github.com/qdm12/ddns-updater)
+- [Hetzner DNS Console](https://dns.hetzner.com/)
+- [Hetzner DNS API Dokumentation](https://dns.hetzner.com/api-docs)
+
 ## Lizenz

 MIT License
--- a/config.json.example
+++ b/config.json.example
@ -0,0 +1,13 @@
+{
+  "settings": [
+    {
+      "provider": "hetzner",
+      "zone_identifier": "your_zone_id_here",
+      "domain": "example.com",
+      "host": "@",
+      "ttl": 60,
+      "token": "your_hetzner_api_token_here",
+      "ip_version": "ipv4"
+    }
+  ]
+}
--- a/docker-compose.yml
+++ b/docker-compose.yml
@ -0,0 +1,26 @@
+version: '3.8'
+
+services:
+  ddns-updater:
+    image: qmcgaw/ddns-updater:latest
+    container_name: hetzner-dyndns
+    restart: unless-stopped
+    ports:
+      - "8000:8000"
+    volumes:
+      - ./data:/updater/data
+    environment:
+      - PERIOD=${PERIOD:-5m}
+      - LOG_LEVEL=${LOG_LEVEL:-info}
+      - TZ=Europe/Berlin
+    healthcheck:
+      test: ["CMD", "wget", "-qO-", "http://localhost:8000/"]
+      interval: 1m
+      timeout: 10s
+      retries: 3
+      start_period: 30s
+    logging:
+      driver: "json-file"
+      options:
+        max-size: "10m"
+        max-file: "3"