Docker-Installation auf verschiedenen Betriebssystemen

Inhaltsverzeichnis

Voraussetzungen
Verzeichnislayout
Setup-Dateien herunterladen
.env konfigurieren
Erster Start
Erster Login
Erster Peer und erste Route
Installation verifizieren
Troubleshooting
Backup und Restore
Updates
Migration bestehender Installationen

1. Voraussetzungen

Hardware

Ressource	Minimum	Empfohlen
CPU	1 vCPU	2 vCPU
RAM	1 GB	2 GB
Platte	20 GB	40 GB (mehr für ausführliche Activity-Logs und Caddy-Access-Logs)

Software

Betriebssystem: Moderne Linux-Distribution (Debian 11+, Ubuntu 22.04+, Fedora, Rocky, Alma, Alpine). Getestet auf Debian 13.
Docker Engine: 24.0 oder neuer
Docker Compose: v2 (seit Docker Engine 23.0 integriert)
WireGuard-Kernelmodul: auf den meisten modernen Kernels vorhanden. Der Container bringt kein externes Install mit, aber WireGuard-Capabilities (NET_ADMIN) müssen dem Container gewährt werden können.

DNS

Bevor der Container gestartet wird, muss ein DNS-A-Record (optional zusätzlich AAAA für IPv6) auf die öffentliche IP des Hosts zeigen:

gate.example.com.   IN  A   198.51.100.42

GateControl nutzt diesen Namen für zwei Zwecke:

Admin-UI via GC_BASE_URL — Caddy fordert automatisch beim ersten Start ein Let's-Encrypt-Zertifikat dafür an.
WireGuard-Endpunkt, falls du zusätzlich GC_WG_HOST=gate.example.com setzt. (GC_WG_HOST kann auch eine blanke öffentliche IP sein, aber derselbe Hostname vereinfacht Peer-Konfigurationen.)

Jede Domain, für die du später eine Reverse-Proxy-Route einrichtest, braucht einen eigenen A-Record, der auf denselben Host zeigt.

Ports

Port	Protokoll	Zweck	Erreichbar von
80	TCP	HTTP → HTTPS Redirect, ACME HTTP-01-Challenge	Internet
443	TCP	HTTPS für Admin-UI und alle Reverse-Proxy-Routen	Internet
443	UDP	HTTP/3 (optional, empfohlen)	Internet
51820	UDP	WireGuard-VPN-Endpunkt	Internet
53	TCP/UDP auf `127.0.0.1` und auf der VPN-Gateway-IP (`10.8.0.1` per Default)	Interner DNS für VPN-Peers	nur Container (Loopback + WG-Interface)

Sofern auf dem Host bereits etwas auf 127.0.0.1:53 lauscht (häufige Ursachen: NetworkManager-dnsmasq, libvirt-dnsmasq, bind9), weigert sich der GateControl-Container zu starten. systemd-resolved nutzt 127.0.0.53 und kollidiert nicht. Das Entrypoint-Skript prüft das explizit und beendet sich mit einer klaren Fehlermeldung, falls es einen anderen Listener findet.

Öffne die ersten vier Ports in deiner Cloud-Firewall / iptables / ufw, bevor du den Container startest.

2. Verzeichnislayout

Lege ein dediziertes Deploy-Verzeichnis an — getrennt von einem eventuell geklonten Source-Repository. Der empfohlene Pfad ist /opt/gatecontrol/:

/opt/gatecontrol/
├── docker-compose.yml    # Image, Ports, Volume
├── .env                  # deine Config (Passwörter, Domain etc.)
├── update.sh             # Helper-Skript zum Pullen + Neustart
└── data/                 # entsteht beim ersten Start — hält DB, Certs, Keys, WG-Config

Warum getrennt vom Source-Repo:

Klares mentales Modell: "Code" und "Config" werden nie vermischt.
Das Source-Repo kann jederzeit frisch geklont, aufgeräumt oder aktualisiert werden, ohne Produktiv-Zustand zu verlieren.
Ein-Zeilen-Backup: tar czf backup.tar.gz /opt/gatecontrol sichert alles.

mkdir -p /opt/gatecontrol
cd /opt/gatecontrol

3. Setup-Dateien herunterladen

Drei Varianten. Alle enden mit denselben Dateien in /opt/gatecontrol/.

Variante A — Interaktives Setup (empfohlen)

setup.sh herunterladen und ausführen. Es installiert Docker, falls es fehlt, führt interaktiv durch die .env-Werte, erzeugt sichere Secrets und startet den Container:

cd /opt/gatecontrol
curl -fsSLO https://github.com/CallMeTechie/gatecontrol/releases/latest/download/setup.sh
curl -fsSLO https://github.com/CallMeTechie/gatecontrol/releases/latest/download/docker-compose.yml
curl -fsSLO https://github.com/CallMeTechie/gatecontrol/releases/latest/download/.env.example
bash setup.sh

Dann direkt zu §6 Erster Login — setup.sh erledigt den Rest.

Variante B — Manuell (volle Kontrolle)

cd /opt/gatecontrol
curl -fsSLO https://github.com/CallMeTechie/gatecontrol/releases/latest/download/docker-compose.yml
curl -fsSLO https://github.com/CallMeTechie/gatecontrol/releases/latest/download/.env.example
curl -fsSLO https://raw.githubusercontent.com/CallMeTechie/gatecontrol/master/update.sh
chmod +x update.sh
cp .env.example .env

Weiter mit §4 .env konfigurieren.

Variante C — Offline / Air-gapped

Für Hosts ohne Internetzugriff während des Installs das Image-Tarball aus einem Release laden:

curl -fsSLO https://github.com/CallMeTechie/gatecontrol/releases/latest/download/gatecontrol-image.tar.gz
docker load < gatecontrol-image.tar.gz
rm gatecontrol-image.tar.gz

Weiter mit docker-compose.yml und .env.example aus Variante B.

4. `.env` konfigurieren

Bearbeite /opt/gatecontrol/.env. Drei Werte sind Pflicht; alle anderen haben sinnvolle Defaults.

Pflicht

Variable	Bedeutung	Beispiel
`GC_ADMIN_PASSWORD`	Anfangspasswort für den `admin`-Account. Wird nur beim ersten Start gelesen — spätere Änderungen laufen über das UI.	`R7!xK2#wPq9$Lm4v`
`GC_WG_HOST`	Öffentliche IP oder Hostname, den VPN-Clients anrufen. Muss aus dem Internet auf UDP/51820 erreichbar sein.	`gate.example.com` oder `198.51.100.42`
`GC_BASE_URL`	Volle URL der Admin-UI. Caddy verwendet den Hostnamen für Let's-Encrypt-Zertifikat.	`https://gate.example.com`

Dringend empfohlen

Variable	Warum	Beispiel
`GC_CADDY_EMAIL`	Let's Encrypt kontaktiert dich bei Ablauf-Warnungen oder Problemen. Ohne funktioniert, aber du hast keinen Recovery-Kanal.	`admin@example.com`

Optional — leer lassen für Auto-Generierung

Variable	Verhalten bei leer
`GC_SECRET`	Ein 48-Byte-Session-Secret wird beim ersten Start generiert und in `/data/.session_secret` (chmod 600) abgelegt.
`GC_ENCRYPTION_KEY`	Ein 32-Byte-AES-256-Key wird generiert und in `/data/.encryption_key` (chmod 600) abgelegt. Unbedingt sichern. Ein Restore der DB ohne passenden Key schlägt fehl.

Die komplette Referenz mit WireGuard-Tuning, Rate-Limits, Timeouts, Client-Update-Repos und Lizenzkey steht in der .env.example im Repository.

Datei editieren

cd /opt/gatecontrol
nano .env   # oder vim oder ein anderer Editor

Die drei Pflichtwerte setzen. Speichern und Editor verlassen.

5. Erster Start

cd /opt/gatecontrol
docker compose up -d
docker compose logs -f

Beim ersten Lauf macht das Entrypoint eine Reihe von Dingen. Zu erwarten ist in etwa diese Reihenfolge:

» Auto-detected egress interface: <name> — das Netzwerk-Interface für VPN-NAT. Bei Fallback auf eth0 ist das auf den meisten Cloud-VMs korrekt; Hosts mit ungewöhnlichen NIC-Namen werden automatisch erkannt.
» MASQUERADE rule active: 10.8.0.0/24 → <iface> — iptables-NAT-Regel ist aktiv.
» Generating WireGuard server keypair... — nur beim Erststart. Der Private-Key landet in ./data/wireguard/wg0.conf mit chmod 600.
» Session secret generated and saved — nur beim Erststart.
» Encryption key generated and saved — nur beim Erststart.
» Generating dnsmasq config (split-horizon for <hostname> → 10.8.0.1)... — interner DNS.
» Exporting Caddy JSON from DB... — auf frischer DB sind noch keine User-Routen vorhanden, aber die Management-UI-Route (GC_BASE_URL-Hostname → 127.0.0.1:3000) wird automatisch injiziert. Du musst diese Route nicht manuell anlegen.
» Starting services via supervisord...
Caddy bootet, holt sich das Let's-Encrypt-Zertifikat für den GC_BASE_URL-Hostnamen. Der erste Cert-Fetch dauert 10–30 Sekunden. Achte auf:
- obtaining certificate gefolgt von
- certificate obtained successfully
- Bei lookup <hostname>: no such host oder unable to fetch certificate ist der DNS noch nicht propagiert — der ACME-Client retry automatisch.
WireGuard startet, Interface wg0 kommt hoch.
Node.js-Webapp startet auf 127.0.0.1:3000. Caddy proxied Requests auf dem GC_BASE_URL-Hostnamen dorthin.

Log-Tail mit Ctrl+C verlassen — der Container läuft im Hintergrund weiter.