WG-Easy 15: Der große Rewrite – Migration & neues Setup mit festem IPv4/IPv6-Netz

Wer WG-Easy betreibt, hat die letzten Wochen zwei Updates erlebt: Erst wurden Klartext-Passwörter in PASSWORD_HASH abgeschafft – und jetzt ist mit WG-Easy 15 ein kompletter Rewrite erschienen. Env-Variablen-Wirrwarr ade: Konfiguration und Benutzerverwaltung wandern in einen Setup-Wizard und ein Admin-Panel. Dieser Artikel zeigt dir die Migration von v14, das frische Compose-Setup mit festem IPv4/IPv6-Netz und warum die Web-UI bei uns nur noch lokal auf 127.0.0.1 lauscht.

Was ist neu in WG-Easy 15?

WG-Easy war immer dann am stärksten, wenn man nichts von WireGuard selbst wissen musste: Container starten, Web-UI öffnen, QR-Code scannen, fertig. Der Preis dafür war eine wachsende Liste an Umgebungsvariablen (WG_HOST, WG_PORT, WG_DEFAULT_DNS, PASSWORD_HASH …), die man sich für jede Installation merken musste.

Mit Version 15 ist damit Schluss: Das Projekt wurde komplett neu geschrieben. Die Einrichtung läuft jetzt über einen Setup-Wizard beim ersten Start, die tägliche Verwaltung über ein Admin-Panel in der Web-UI. Die alten Env-Variablen werden in v15 nicht mehr verwendet – wer sie mitschleppt, bekommt unter Umständen einen Container, der nicht so startet wie erwartet.

Die wichtigsten Neuerungen im Überblick:

• Setup-Wizard: Beim ersten Start legst du Benutzerkonto, Host, Port und DNS direkt in der Oberfläche an.
• Admin-Panel: Alle Einstellungen lassen sich später in der Web-UI ändern – ohne Container-Neustart mit neuen Env-Variablen.
• 2FA-Unterstützung und OIDC (Google, GitHub, Authelia, Authentik & Co.).
• One-Time-Links, Client-Expiration und Per-Client-Firewall-Regeln (experimentell, iptables-basiert).
• Vollwertiges IPv6 und CIDR-Support statt fester 10.8.0.0/24-Konfiguration.
• Statistik & Tx/Rx-Diagramme pro verbundenem Client, Prometheus-Metriken, Multilanguage-UI.
• Neue, reduzierte Env-Variablen: PORT, HOST, INSECURE, DISABLE_IPV6, DISABLE_VERSION_CHECK, TRUSTED_PROXIES.

Achtung: Den richtigen Image-Tag verwenden

Klingt banal, ist aber die häufigste Fehlerquelle nach dem Update: Das Image ghcr.io/wg-easy/wg-easy wird ohne Tag bzw. mit :latest weiterhin auf die alte v14-Linie zeigen. Wer „latest“ zieht, bleibt also auf dem alten Stand – oder zieht sich beim Tag-Wechsel ungewollt einen Rewrite unter.

Migration von v14 nach v15

Der Weg vom alten zum neuen Stand ist dokumentiert und in sechs Schritten erledigt:

1. Backup erstellen: In der alten Web-UI auf „Backup“ klicken – das lädt eine wg0.json herunter. Alternativ die Datei direkt aus dem Container-Volume kopieren.
2. Alte Env-Variablen notieren: Sie werden nicht automatisch übernommen – WG_HOST & Co. stellst du nachher im Wizard bzw. Admin-Panel neu ein.
3. Alten Container stoppen: docker compose down bzw. docker stop wg-easy.
4. Neues Compose-Setup anlegen (siehe unten) und mit dem Image-Tag :15 starten: docker compose up -d.
5. Wizard: Beim ersten Start wählst du „Ich habe bereits eine Konfiguration“ und lädst die wg0.json hoch.
6. HTTP prüfen: Wenn du die Web-UI nur über HTTP erreichst, musst du INSECURE=true setzen (mehr dazu unten).

Das neue Setup: docker-compose.yml im Detail

So sieht eine aktuelle Konfiguration für WG-Easy 15 aus – angelehnt an die offizielle Vorlage, aber mit zwei Anpassungen, die wir empfehlen: Die Web-UI wird nur auf localhost gebunden (Port 50538) und die Daten liegen in einem Bind-Mount unter ./wg-easy.

services:
  wg-easy:
    #environment:
    #  Optional:
    #  - PORT=51821
    #  - HOST=0.0.0.0
    #  - INSECURE=false

    image: ghcr.io/wg-easy/wg-easy:15
    container_name: wg-easy
    networks:
      wg:
        ipv4_address: 10.42.42.42
        ipv6_address: fdcc:ad94:bacf:61a3::2a
    volumes:
      - ./wg-easy:/etc/wireguard
      - /lib/modules:/lib/modules:ro
    ports:
      - 51820:51820/udp
      - 127.0.0.1:50538:51821/tcp
    restart: unless-stopped
    cap_add:
      - NET_ADMIN
      - SYS_MODULE
      # - NET_RAW # ⚠️ Uncomment if using Podman
    sysctls:
      - net.ipv4.ip_forward=1
      - net.ipv4.conf.all.src_valid_mark=1
      - net.ipv6.conf.all.disable_ipv6=0
      - net.ipv6.conf.all.forwarding=1
      - net.ipv6.conf.default.forwarding=1
networks:
  wg:
    driver: bridge
    enable_ipv6: true
    ipam:
      driver: default
      config:
        - subnet: 10.42.42.0/24
        - subnet: fdcc:ad94:bacf:61a3::/64

Zeile für Zeile erklärt:

• image: ghcr.io/wg-easy/wg-easy:15 – bewusst auf die Major-Version gepinnt (siehe oben).
• Statische Container-IPs: Der Container bekommt im Netz wg feste Adressen (10.42.42.42 und fdcc:ad94:bacf:61a3::2a). Praktisch, wenn andere Container den VPN-Server gezielt ansprechen sollen – die Adressen bleiben über Neustarts hinweg stabil.
• ./wg-easy:/etc/wireguard – hier liegen Konfiguration (wg0.json), Server-Keys und Clients. Dieser Ordner ist dein Backup.
• /lib/modules:/lib/modules:ro – stellt die Kernel-Module des Hosts im Container bereit (nötig, damit WireGuard bzw. die Firewall-Regeln die Module laden können).
• 51820:51820/udp – der eigentliche WireGuard-Port, muss von außen erreichbar sein.
• 127.0.0.1:50538:51821/tcp – die Web-UI wird nicht öffentlich exponiert, sondern lauscht nur lokal auf Port 50538. Erreichbar ist sie damit nur über deinen Reverse Proxy, einen SSH-Tunnel oder direkt auf dem Host. 51821 ist der interne Port der UI (per PORT änderbar), 50538 die von dir gewählte äußere Nummer.
• cap_add – NET_ADMIN (Netzwerk-/Firewall-Konfiguration) und SYS_MODULE (Kernel-Module laden). Den auskommentierten NET_RAW-Capability brauchst du nur unter Podman.
• sysctls – aktiviert IP-Forwarding für IPv4 und IPv6 (inkl. Reaktivierung von IPv6 im Container), damit der Server als Router für deine VPN-Clients arbeitet.
• networks → wg – ein eigenes Bridge-Netz mit enable_ipv6: true und je einem IPv4- und IPv6-Subnetz. WG-Easy weist den Clients daraus die Adressen zu.

Netzwerk & Ports verstehen

Die Konfiguration trennt bewusst zwei Welten: Das WireGuard-Tunnelnetz (UDP 51820) muss öffentlich erreichbar sein – hier verbinden sich deine Clients. Das Webinterface dagegen ist reine Verwaltung und sollte nie unverschlüsselt im Internet hängen. Indem wir es nur auf 127.0.0.1 binden, ist es für Bots und Scanner von außen schlicht unsichtbar.

Üblich ist dann der Zugriff über einen Reverse Proxy, der die UI per HTTPS ausliefert und die Anfrage an 127.0.0.1:50538 weiterreicht – genau das Setup, das wir auch im großen Proxy-Vergleich empfehlen. Wer kein HTTPS davor schaltet und die UI direkt per HTTP anspricht (etwa per SSH-Tunnel), muss dem Container das mitteilen:

    environment:
      # Web-UI wird über HTTP erreicht (z. B. hinter Proxy, der TLS terminiert)
      - INSECURE=true
      # Origin-IP deines Proxys/Netzwerks für korrekte Security-Logs (CrowdSec etc.)
      - TRUSTED_PROXIES=172.18.0.2,fd00:1234::/64

Erster Start, Setup-Wizard & Reverse Proxy

Nach docker compose up -d öffnest du die Web-UI – bei unserem Setup also über deinen Proxy bzw. Tunnel auf https://vpn.deinedomain.de. Beim allerersten Start erscheint der Setup-Wizard:

1. Benutzerkonto: Admin-Username und Passwort vergeben (und bestätigen). Dieses Konto ersetzt das frühere PASSWORD_HASH-Konstrukt – 2FA kannst du direkt danach einrichten.
2. „Hast du schon eine Konfiguration?“: Bei der Migration von v14 hier „Ja“ wählen und die gesicherte wg0.json hochladen. Für einen frischen Start „Nein“ wählen.
3. Host & Port: Die Adresse, unter der Clients den Server erreichen (Domain oder IP – IPv6-Adressen in eckigen Klammern, z. B. [2001:db8::1]) sowie den WireGuard-Port (Standard 51820).

Der Wizard erscheint nur beim ersten Start. Wer die Einrichtung vollständig automatisieren will (etwa mit Ansible), nutzt die INIT_*-Variablen – sie werden ausschließlich beim ersten Start ausgewertet und danach ignoriert:

    environment:
      - INIT_ENABLED=true
      - INIT_USERNAME=admin
      - INIT_PASSWORD=Ein!Langes#Passwort2026
      - INIT_HOST=vpn.deinedomain.de
      - INIT_PORT=51820
      - INIT_DNS=1.1.1.1,8.8.8.8

Läuft WG-Easy hinter einem Reverse Proxy, empfehlen die Maintainer außerdem, das Raten-Limitieren nicht WG-Easy zu überlassen (es macht keins), sondern dem Proxy – insbesondere für /api/auth/password, /api/auth/verify-2fa und /cnf/*. Mit TRUSTED_PROXIES landen dabei die echten Client-IPs in den Security-Logs, sodass Tools wie CrowdSec Brute-Force-Versuche erkennen können.

Sicherheit & Verwaltung im Admin-Panel

• Zwei-Faktor-Authentifizierung aktivieren – die UI unterstützt 2FA nativ, bei einem im Internet erreichbaren Admin-Panel ist das Pflicht.
• Per-Client-Firewall: Im Admin-Panel → Interface lässt sich pro Client einschränken, welche Ziele er durch den Tunnel erreichen darf. Das Feature ist aktuell noch als experimentell markiert – vor Produktiv-Einsatz testen.
• Backup: Der „Backup“-Button in der UI exportiert wg0.json; zusätzlich sicherst du den Ordner ./wg-easy. Damit ist eine komplette Wiederherstellung (inkl. aller Clients) möglich.
• Stop/Start-Kommando: WG-Easy per docker compose up/down verwalten – nicht per start/stop, sonst kann der Container in einem inkonsistenten Zustand zurückbleiben.
• Version pinnen & Update-Routine: Mit Tag :15 fährst du Updates über docker compose pull && docker compose up -d – ohne Angst vor Major-Brüchen.

Fehlerbehebung: Die häufigsten Stolperfallen

Fazit

WG-Easy 15 ist mehr als ein Versionssprung – es ist der konsequente Abschluss der Sicherheits- und Bedien-Offensive der letzten Monate. Statt Klartext-Passwörter und Dutzender Env-Variablen gibt es ein sauberes Benutzerkonto, 2FA und ein Admin-Panel, in dem sich alles Nötige klicken lässt. Die Einrichtung mit festem IPv4/IPv6-Netz und lokal gebundener Web-UI ist dabei so aufgebaut, wie wir es für einen produktiven VPN-Server empfehlen: WireGuard-Port offen, Verwaltung nur für dich.