codeluxe1/ddns-manager repository overview

⁠DDNS Manager

Sichere Weboberflaeche fuer IPv64/DDNS-Updates mit Erstinstallation im Browser, Login, optionalem Passkey/WebAuthn-Login, MySQL/MariaDB-Unterstuetzung und gehaertetem Docker-Image.

⁠Docker Image

codeluxe1/ddns-manager:latest
codeluxe1/ddns-manager:v1

Unterstuetzte Plattformen:

linux/amd64
linux/arm64

⁠Funktionen

• Erstinstallation komplett im Browser unter /setup
• Keine Datenbank- oder Secret-Variablen fuer den normalen Docker-Start noetig
• Automatisch erzeugte interne App-Schluessel im Docker-Volume
• MySQL/MariaDB-Daten werden beim Setup im Browser eingetragen
• Geschuetzte Weboberflaeche mit Login
• Optionaler Passkey-Login per WebAuthn
• Domain-Verwaltung fuer DDNS-Updates
• Manuelle und automatische DDNS-Updates
• IPv4- und IPv6-Erkennung
• API-Tokens werden verschluesselt gespeichert
• Docker-Container laeuft als Non-root-User
• Integrierter Healthcheck unter /healthz

⁠Schnellstart Mit Docker Compose

Ordner anlegen:

mkdir -p ~/ddns-manager
cd ~/ddns-manager

docker-compose.yml erstellen:

services:
  app:
    image: codeluxe1/ddns-manager:latest
    container_name: ddns-manager-app
    restart: unless-stopped
    ports:
      - "127.0.0.1:8087:5000"
    volumes:
      - ddns_data:/data
    security_opt:
      - no-new-privileges:true
    read_only: true
    tmpfs:
      - /tmp

volumes:
  ddns_data:

networks:
  default:
    name: ddns-manager_net

Container starten:

docker compose pull
docker compose up -d
docker compose logs -f app

Healthcheck:

curl -f http://127.0.0.1:8087/healthz

Setup-Seite oeffnen:

http://127.0.0.1:8087/setup

Wenn die App direkt im LAN erreichbar sein soll, aendere die ports-Zeile:

ports:
  - "0.0.0.0:8087:5000"

Danach:

http://<server-ip>:8087/setup

⁠Erstinstallation Im Browser

Beim ersten Start gibst du alles im Browser ein:

• Datenbank-Host
• Datenbank-Port
• Datenbankname
• Datenbankbenutzer
• Datenbankpasswort
• TLS/SSL-Modus fuer die Datenbank
• Admin-Benutzername
• Admin-Passwort
• DDNS-Provider-URL
• Update-Intervall
• IPv4/IPv6-Auswahl
• Optional: Passkeys aktivieren

Nach dem Absenden prueft die App die Datenbankverbindung, erstellt die Tabellen und speichert die Konfiguration im Docker-Volume. Danach startet die App neu und du kannst dich unter /login anmelden.

⁠Datenbank Vorbereiten

Empfohlen wird MySQL oder MariaDB.

Beispielrechte:

CREATE DATABASE ddns_manager CHARACTER SET utf8mb4 COLLATE utf8mb4_unicode_ci;
CREATE USER 'ddns_manager'@'%' IDENTIFIED BY '<starkes-passwort>';
GRANT SELECT, INSERT, UPDATE, DELETE, CREATE, ALTER, INDEX ON ddns_manager.* TO 'ddns_manager'@'%';
FLUSH PRIVILEGES;

Fuer externe Datenbanken wird TLS empfohlen. Im Browser-Setup kannst du den SSL-Modus auswaehlen. Nutze disabled nur in vertrauenswuerdigen privaten Netzwerken.

⁠Was Im Docker-Volume Gespeichert Wird

Die App speichert technische Konfiguration im Volume ddns_data:

• /data/runtime_secrets.json: automatisch erzeugte interne App-Schluessel
• /data/runtime_config.json: Datenbank-Konfiguration, Datenbankpasswort verschluesselt
• /data/bootstrap_setup.db: interne temporaere SQLite-Datei fuer die erste Setup-Seite

Diese Dateien nicht loeschen, wenn die Installation weiter funktionieren soll.

⁠Passkeys / WebAuthn

Passkeys sollten mit HTTPS und einem festen Hostnamen genutzt werden.

Wenn du einen Reverse Proxy verwendest:

• Leite Host korrekt weiter.
• Leite X-Forwarded-Proto korrekt weiter.
• Nutze im Browser immer dieselbe HTTPS-Adresse.

Die App verwendet standardmaessig die aktuelle Browser-Adresse als WebAuthn-Origin. Nach der Erstinstallation kannst du Passkeys in den Einstellungen aktivieren und registrieren.

⁠Alternative Mit docker run

docker run -d \
  --name ddns-manager-app \
  --restart unless-stopped \
  -p 127.0.0.1:8087:5000 \
  -v ddns_data:/data \
  --read-only \
  --tmpfs /tmp \
  --security-opt no-new-privileges:true \
  codeluxe1/ddns-manager:latest

⁠Update

cd ~/ddns-manager
docker compose pull
docker compose up -d
docker image prune -f

Nutze codeluxe1/ddns-manager:v1 statt latest, wenn du einen festen Release-Tag verwenden moechtest.

⁠Backup

Sichere vor allem deine MySQL/MariaDB-Datenbank. Zusaetzlich solltest du das Docker-Volume sichern, weil dort die internen Schluessel und die Datenbank-Verbindungskonfiguration liegen.

Beispiel:

docker run --rm \
  -v ddns-manager_ddns_data:/data \
  -v "$PWD:/backup" \
  alpine tar czf /backup/ddns-manager-data.tar.gz -C / data

Wenn dein Compose-Projekt anders heisst, kann der Volume-Name abweichen. Pruefe ihn mit:

docker volume ls

⁠Wichtige Sicherheitshinweise

• Das Docker-Volume ddns_data muss dauerhaft erhalten bleiben.
• Compose-Dateien oder Backups mit echten Secrets nicht oeffentlich machen.
• Bei Nutzung eines Reverse Proxys am besten nur an 127.0.0.1 binden.
• Fuer produktive Installationen und Passkeys HTTPS verwenden.
• Datenbankzugriff per Firewall, privatem Netzwerk oder IP-Allowlist einschraenken.

⁠Fehlerbehebung

• Setup-Seite erscheint immer wieder: Pruefe, ob der Container nach dem Speichern neu gestartet wurde und das Volume ddns_data erhalten bleibt.
• Datenbankverbindung schlaegt fehl: Host, Port, Benutzer, Passwort, TLS-Modus und Firewall pruefen.
• App ist im LAN nicht erreichbar: ports auf 0.0.0.0:8087:5000 setzen oder Reverse Proxy verwenden.
• Passkey-Login funktioniert nicht: HTTPS, Hostname und Reverse-Proxy-Header pruefen.
• /setup leitet auf /login weiter: Die Erstinstallation ist bereits abgeschlossen.
• Container startet nicht: docker compose logs -f app ausfuehren.