Erste Schritte
1. Einleitung & Grundkonzepte
GateControl ist ein selbst-gehostetes Admin-Tool, das drei Komponenten kombiniert:
- WireGuard für den VPN-Tunnel. Jeder verbundene Endpunkt ist ein Peer
mit eigener IP im VPN-Subnetz (Standard
10.8.0.0/24). - Caddy als Reverse-Proxy mit automatischem Let's Encrypt. Domains werden über sogenannte Routen auf Backends hinter dem Tunnel gemappt.
- Node.js-Admin-Server mit SQLite-Datenbank. Stellt die Web-UI und die JSON-HTTP-API bereit, synchronisiert WireGuard-State und pusht die Caddy-Config zur Laufzeit über die Admin-API.
Das Ganze läuft in einem einzelnen Docker-Container mit network_mode: host,
orchestriert per supervisord.
Optionale Zusatzkomponenten
- Home-Gateway — ein kleiner Companion-Container, den du im Heimnetz (NAS, Raspberry Pi, Mini-PC) betreibst. Er baut den WireGuard-Tunnel ausgehend zum Server auf, so dass du keine Port-Weiterleitung im Heim-Router brauchst. Der Server routet HTTP- und L4-Traffic durch den Tunnel bis zum Gateway, dieser forwarded lokal ins LAN. Siehe Home-Gateway.
- Desktop-/Mobil-Client — der offizielle GateControl-Client (Windows, Android, iOS) ist eine bequeme Hülle um einen WireGuard-Peer plus Dienste-Browser, RDP-Launcher und Auto-Update. Normale WireGuard-Clients funktionieren genauso.
- Internal DNS — eingebauter dnsmasq, der Peers per Hostname innerhalb
des VPN-Subnetzes auflöst (
nas.vpn.example.com → 10.8.0.12). Optional, lizenz-gated. Siehe Domains & DNS.
Begriffe
| Begriff | Bedeutung |
|---|---|
| Peer | WireGuard-Endpunkt. Entweder ein normaler Client (Laptop, Handy, NAS) oder ein Home-Gateway. |
| Gateway oder Gateway-Peer | Spezieller Peer-Typ (peer_type=gateway). Gateways sehen Routen und dürfen LAN-Ziele forwarden. |
| Route | Ein Domain-/Port-Eintrag in der Caddy-Config. Wird auf einen Peer oder ein Gateway gemappt. |
| Target-Kind | Das Ziel einer Route. peer = direkt zur WG-IP des Peers, gateway = durch den Gateway ins LAN. |
| Route-Typ | http (Layer 7, mit TLS-Termination), l4 (rohes TCP/UDP), rdp (eigener Wizard, produziert L4/Gateway-Route plus Credential-Vault). |
| Hostname-Source | Woher der interne Hostname eines Peers kommt: admin (Web-UI) oder agent (vom Client-Heartbeat gemeldet). |
2. Erste Schritte
2.1 Login
Die Admin-UI erreichst du unter der in GC_BASE_URL konfigurierten Domain.
Nach dem ersten Start gibt es einen Admin-Benutzer mit dem im Setup gesetzten
Passwort. Öffne / → Login mit admin und dem Passwort.
Nach dem Login landest du auf dem Dashboard mit Kacheln für verbundene
Peers, aktive Routen, heutigen Traffic, durchschnittliche Latenz und der
Verfügbarkeits-Karte (zeigt aggregiert, wie viele überwachte Routen gerade
erreichbar sind — klickbar zu /routes).
2.2 Admin-Passwort ändern
Oben rechts auf den Benutzernamen klicken → Profil → Passwort ändern. Wenn die Passwort-Komplexität unter Settings → Sicherheit eingeschaltet ist, werden Mindestlänge, Groß-/Klein-/Sonderzeichen erzwungen.
2.3 Ersten Peer anlegen
Um etwas Nützliches zu tun, brauchst du mindestens einen Peer:
- Sidebar → Peers & Clients
- Oben rechts + Hinzufügen
- Name vergeben (z.B.
laptop-mario). Der Name darf nur alphanumerisch plus Bindestrich sein und muss eindeutig sein. - Optional: Beschreibung, Gruppe, Tags, Ablaufdatum.
- Home Gateway lässt du bei einem normalen Client aus — dazu später mehr.
- Anlegen
Server generiert automatisch einen privaten WireGuard-Key, einen Preshared-Key und die nächste freie IP. Du bekommst danach eine Config als Download oder QR-Code. Die Config importierst du in die WireGuard-App auf dem Gerät.
2.4 Erste Route anlegen
- Sidebar → Domains & Routen
- + Route hinzufügen — öffnet den 6-Schritt-Wizard
- Durchklicken: Ziel (Peer + Port) → Transport (HTTPS erzwingen) → Auth (keine) → Zugriff → Zuverlässigkeit → Übersicht → Speichern & Caddy reload
Wenn die Domain per DNS auf deinen Server zeigt, beantragt Caddy sofort ein Let's-Encrypt-Zertifikat im Hintergrund.