Compare commits

...

2 Commits

Author SHA1 Message Date
Schulz 1b7ebf1b00 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>
2026-02-16 22:28:56 +01:00
Schulz 75efdcc16d Add DynDNS implementation v0.2.0
- Implement Python-based DynDNS client with Hetzner DNS API integration
- Add automatic IP detection for IPv4/IPv6
- Add automatic zone ID discovery
- Add Docker configuration with multi-stage build
- Add Docker Compose setup with restart policy
- Add environment variable configuration
- Add comprehensive documentation (CLAUDE.md)
- Add example configuration (.env.example)
- Add health check for container monitoring

Co-Authored-By: Claude Sonnet 4.5 <noreply@anthropic.com>
2026-02-16 22:21:54 +01:00
7 changed files with 462 additions and 29 deletions

9
.env.example Normal file
View File

@ -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

5
.gitignore vendored
View File

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

View File

@ -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/). 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 ## [0.1.0] - 2026-02-16
### Hinzugefügt ### Hinzugefügt

202
CLAUDE.md Normal file
View File

@ -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)

187
README.md
View File

@ -1,14 +1,18 @@
# DynDNS Docker für Hetzner DNS # 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 ## Features
- Automatische Erkennung von IP-Änderungen - ✅ Automatische Erkennung von IP-Änderungen
- Integration mit Hetzner DNS API - ✅ Integration mit Hetzner DNS API
- Konfigurierbare Check-Intervalle - ✅ Web-UI für Überwachung und Verwaltung (Port 8000)
- Docker-Container für einfaches Deployment - ✅ Konfigurierbare Check-Intervalle
- Umgebungsvariablen für sichere Konfiguration - ✅ 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 ## Voraussetzungen
@ -25,43 +29,125 @@ git clone <repository-url>
cd dyndns-docker cd dyndns-docker
``` ```
### 2. Konfiguration ### 2. Konfiguration erstellen
Kopieren Sie die Beispiel-Konfigurationsdatei und passen Sie sie an: #### a) Umgebungsvariablen (optional)
```bash ```bash
cp .env.example .env cp .env.example .env
``` ```
Bearbeiten Sie die `.env` Datei mit Ihren Daten: Bearbeiten Sie `.env` für optionale Einstellungen:
```env ```env
HETZNER_API_TOKEN=your_api_token_here PERIOD=5m # Update-Intervall
DOMAIN=example.com LOG_LEVEL=info # Log-Level
RECORD_NAME=home
RECORD_TYPE=A
CHECK_INTERVAL=300
``` ```
### 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 ```bash
docker-compose up -d 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 ## 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 ### Umgebungsvariablen
| Variable | Beschreibung | Beispiel | | Variable | Beschreibung | Standard |
|----------|-------------|----------| |----------|-------------|----------|
| `HETZNER_API_TOKEN` | Hetzner DNS API Token | `abc123...` | | `PERIOD` | Update-Intervall | `5m` |
| `ZONE_ID` | Hetzner DNS Zone ID (optional, wird automatisch ermittelt) | `xyz789...` | | `LOG_LEVEL` | Log-Level | `info` |
| `DOMAIN` | Domain-Name | `example.com` |
| `RECORD_NAME` | DNS Record Name | `home` oder `@` für Root | ### Mehrere Domains konfigurieren
| `RECORD_TYPE` | DNS Record Typ | `A` (IPv4) oder `AAAA` (IPv6) |
| `CHECK_INTERVAL` | Prüfintervall in Sekunden | `300` (5 Minuten) | Sie können mehrere Domains in `data/config.json` hinzufügen:
| `LOG_LEVEL` | Log-Level | `INFO`, `DEBUG`, `WARNING` |
```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 ## Verwendung
@ -89,12 +175,49 @@ docker-compose restart
docker-compose down docker-compose down
``` ```
## Hetzner DNS API Token erstellen ### Konfiguration neu laden
1. Melden Sie sich im [Hetzner DNS Console](https://dns.hetzner.com/) an Nach Änderungen an `data/config.json`:
2. Gehen Sie zu "API Tokens"
3. Erstellen Sie einen neuen API Token mit Lese- und Schreibrechten ```bash
4. Kopieren Sie den Token in Ihre `.env` Datei 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 ## Versioning
@ -103,6 +226,12 @@ Dieses Projekt folgt einer vereinfachten Versionierungsstruktur:
- **0.0.1**: Kleine Änderungen (Bugfixes, kleinere Verbesserungen) - **0.0.1**: Kleine Änderungen (Bugfixes, kleinere Verbesserungen)
- **1.x**: Major Releases (nur nach Anweisung) - **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 ## Lizenz
MIT License MIT License

13
config.json.example Normal file
View File

@ -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"
}
]
}

26
docker-compose.yml Normal file
View File

@ -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"