Pangolin installieren: Du richtest ein öffentliches Pangolin-Gateway ein, verbindest deinen Homeserver über Newt und erreichst deinen Dienst anschließend verschlüsselt unter https://photos.example.com. Alle Domain- und Servernamen sind Beispiele.
Das Ergebnis: Du hast eine erreichbare Ressource mit eigener Domain, funktionierendem HTTPS und einer geprüften Tunnelverbindung. Die Anleitung zeigt außerdem, wie du DNS, Ports und typische Fehler überprüfst.
Stand: 3. November 2026. Die Anleitung folgt der offiziellen Pangolin-Quick-Install-Dokumentation. Sie beschreibt eine frische Installation auf einem eigenen Linux-Server mit öffentlicher IP. Wer Pangolin bereits produktiv einsetzt, darf die Befehle nicht ungeprüft über die bestehende Konfiguration ausführen.
Was ist Pangolin – und wie funktioniert der Tunnel?
Pangolin ist eine selbst hostbare Plattform für geschützten Zugriff auf interne Anwendungen. Auf dem öffentlich erreichbaren Gateway arbeiten eine Verwaltungsoberfläche, ein Reverse Proxy (Traefik) und – sofern aktiviert – die Tunnel-Komponente Gerbil. Ein Connector im Heimnetz (Pangolin Site beziehungsweise Newt) baut die Verbindung nach außen auf. Ein Webaufruf an app.example.com geht zuerst zum Gateway und dann über die Verbindung zum Zielsystem im privaten Netz.
Ein Pangolin-Tunnel ist nicht dasselbe wie ein Cloudflare Tunnel: Pangolin kann den Zugriff inklusive Authentifizierung und Netzwerktunnel selbst verwalten. Cloudflare kann als DNS-Anbieter eingesetzt werden; ein zusätzlicher Cloudflare Tunnel ist für den hier beschriebenen Standardaufbau nicht erforderlich.
1. Voraussetzungen und sinnvolle Architektur
- Ein Linux-Server mit öffentlicher IP (beispielsweise Ubuntu LTS oder Debian) für das Pangolin-Gateway; für Anfänger ist ein separater VPS besonders übersichtlich.
- Eine Domain mit Zugriff auf ihre DNS-Verwaltung, beispielsweise
example.com, und eine E-Mail-Adresse für Let’s Encrypt. - Administrator-/sudo-Rechte und Zugriff per SSH. Die Gateway-Ports sind standardmäßig TCP
80und443, UDP51820für Site-Tunnel und bei Verwendung von Pangolin-Clients UDP21820. - Ein Zielserver im Heimnetz mit funktionierendem Dienst, etwa
192.168.1.50:8123für eine Home-Assistant-Instanz. Das ist ein Beispiel, keine allgemeingültige Adresse.
Wichtig für TrueNAS, Docker und bestehende Reverse Proxys: Prüfe vor der Installation, ob auf dem vorgesehenen Host bereits Apache, Nginx, Pangolin, Cloudflare-Connectoren oder Coolifys Traefik an TCP 80/443 gebunden sind. Zwei unabhängige Proxys können dieselben Host-Ports nicht gleichzeitig belegen. Verwende im Zweifel einen separaten Gateway-Host oder einen einzigen vorgelagerten Reverse Proxy.
sudo ss -lntup | grep -E ":(80|443|51820|21820)\b" || true
sudo docker ps --format "table {{.Names}}\t{{.Ports}}"2. DNS: Domain und *.example.com vorbereiten
Beim DNS-Anbieter legst du für den Standardfall die folgenden Einträge an. Ersetze 203.0.113.10 durch deine echte öffentliche Gateway-IP; die hier genannte Adresse ist nur eine reservierte Dokumentationsadresse.
Typ Name Ziel Zweck
A pangolin 203.0.113.10 Verwaltungsoberfläche
A * 203.0.113.10 Andere Subdomains
A @ 203.0.113.10 Optional: HauptdomainEin Wildcard-DNS-Eintrag *.example.com führt passende Subdomains zur selben IP. Er veröffentlicht nicht automatisch jede Anwendung: Erst eine Pangolin-Ressource mit passendem Hostnamen und Ziel macht die Route funktionsfähig. Explizite DNS-Einträge können Vorrang haben; die Hauptdomain example.com ist nicht im Wildcard-Eintrag enthalten.
Wenn du Cloudflare als DNS-Anbieter nutzt, beginne für die direkte Gateway-Installation mit DNS only, damit Let’s Encrypt und die Fehlersuche übersichtlich bleiben. Bei aktiviertem Cloudflare-Proxy zeigen öffentliche DNS-Abfragen stattdessen meist Cloudflare-IP-Adressen. Cloudflare Tunnel ist eine andere Architektur und ersetzt nicht automatisch die UDP-Tunnelports von Pangolin.
dig @1.1.1.1 pangolin.example.com A +short
dig @1.1.1.1 test.example.com A +short3. Firewall absichern, ohne SSH auszusperren
Auf Ubuntu mit UFW kannst du die Ports gezielt öffnen. Stelle zuerst sicher, dass SSH beziehungsweise dein eigener SSH-Port erlaubt ist, und prüfe zusätzlich die Firewall des VPS-Providers. Öffne UDP 21820 nur, wenn du die zugehörigen Client-Tunnel verwendest.
sudo ufw allow OpenSSH
sudo ufw allow 80/tcp
sudo ufw allow 443/tcp
sudo ufw allow 51820/udp
# Nur bei Bedarf:
sudo ufw allow 21820/udp
sudo ufw status numbered4. Pangolin Community Edition offiziell installieren
Melde dich per SSH am neuen Gateway an. Erstelle einen separaten Ordner, lade den Installer aus der offiziellen Quelle herunter und starte ihn. Fremde Installationsskripte solltest du vor Ausführung prüfen; in produktiven Umgebungen sind eine VM und ein Snapshot empfehlenswert.
mkdir -p ~/pangolin-install
cd ~/pangolin-install
curl -fsSL https://static.pangolin.net/get-installer.sh | bash
sudo ./installerDer Assistent fragt nach der Edition (Community Edition oder Enterprise), der Basisdomain (example.com), der Dashboard-Domain (pangolin.example.com), der Let’s-Encrypt-E-Mail sowie der Tunnel-Komponente Gerbil. Für den hier erklärten Zugriff auf private Server wählst du Gerbil. SMTP lässt sich gegebenenfalls später konfigurieren.
Bestätige die Konfiguration erst, wenn DNS, Ports, gewählte Domain und Installationsordner passen. Der Installer erzeugt seine Konfigurationsdateien im aktuellen Arbeitsverzeichnis und startet die benötigten Container.
5. Erstes Administrator-Konto und Organisation anlegen
Öffne nach erfolgreicher Installation die vom Installer ausgegebene URL, normalerweise https://pangolin.example.com/auth/initial-setup. Für das erste Konto benötigst du ein Initial-Setup-Token, das im Installer oder den Pangolin-Logs angezeigt wird. Behandle es vertraulich.
cd ~/pangolin-install
sudo docker compose ps
sudo docker compose logs --tail=100 pangolinErfolgskontrolle: docker compose ps zeigt laufende Pangolin-Komponenten ohne fortlaufende Neustarts. In den Logs dürfen keine anhaltenden Portbindungs- oder Konfigurationsfehler stehen. Die öffentliche HTTPS-Adresse testest du erst, nachdem DNS und Zertifikat konfiguriert sind. Warum? Ein gestarteter Container beweist noch nicht, dass Newt, DNS und die Ressourcenroute funktionieren.
Gib das Setup-Token auf der Einrichtungsseite ein, richte ein starkes Passwort ein und lege deine Organisation an. Aktiviere möglichst MFA beziehungsweise einen vertrauenswürdigen Identity Provider. Öffentliche Registrierung sollte nur erlaubt sein, wenn du sie tatsächlich benötigst.
Bildquelle: Pangolin-Dokumentation (offizieller Screenshot) – Ressourcenverwaltung. Abbildung kann je nach Version abweichen.
6. Deinen Homeserver als Site verbinden
Erstelle im Pangolin-Dashboard unter Sites eine neue Site für dein Heimnetz. Pangolin zeigt dir dann die passende Installationsanweisung für den empfohlenen Connector an. In aktuellen Versionen kann die CLI für neue Sites empfohlen werden; Newt bleibt als leichter Connector verfügbar. Kopiere die konkret in deinem Dashboard erzeugten Zugangsdaten, statt Beispiel-IDs zu übernehmen.
Wenn du Newt als Docker-Container verwendest, entspricht die Struktur ungefähr diesem Beispiel. Ersetze die Platzhalter durch die vom Dashboard ausgegebenen Werte. Der Endpunkt muss dein eigenes Pangolin-Gateway sein.
services:
newt:
image: fosrl/newt:latest
restart: unless-stopped
environment:
PANGOLIN_ENDPOINT: "https://pangolin.example.com"
NEWT_ID: "${NEWT_ID}"
NEWT_SECRET: "${NEWT_SECRET}"Speichere die echten Secrets außerhalb des Compose-Dokuments in einer geschützten .env-Datei, zum Beispiel mit chmod 600 .env. Starte den Connector auf einem System, das den Zielserver im Heimnetz erreichen kann, und prüfe im Pangolin-Dashboard, dass die Site online ist.
7. Erste Ressource auf eine Subdomain legen
- Im Dashboard eine öffentliche HTTP/HTTPS-Ressource anlegen und die gewünschte Site auswählen.
- Als öffentliche Adresse etwa
ha.example.comeintragen. Dafür muss der DNS-Eintrag zur Pangolin-Instanz führen. - Als Target die aus Sicht des Connectors erreichbare interne IP beziehungsweise den Hostnamen und den internen Dienstport konfigurieren, zum Beispiel
192.168.1.50und8123. - Das passende Protokoll (HTTP oder HTTPS) für die Verbindung zum internen Dienst wählen, speichern und die Ressourcenberechtigungen prüfen.
- Die Subdomain im Browser testen und gegebenenfalls den Dienst selbst für den Betrieb hinter einem Reverse Proxy konfigurieren (vertrauenswürdige Proxys, öffentliche Basis-URL, WebSockets).
Die öffentliche Domain endet auf HTTPS-Port 443; der Target-Port 8123 bleibt intern. Du trägst bei DNS also nicht :8123 ein – DNS kennt keine Webanwendungs-Ports. Für eine zweite App wird eine eigene Ressource mit beispielsweise notes.example.com angelegt.
8. HTTPS, Wildcard-Zertifikate und Cloudflare korrekt verstehen
Wildcard-DNS ist nicht Wildcard-SSL. Für ha.example.com kann Pangolin ein normales Zertifikat beschaffen. Ein gemeinsames Zertifikat für *.example.com erfordert bei Let’s Encrypt die DNS-01-Validierung. Ein Wildcard-Zertifikat deckt typischerweise ha.example.com, aber weder automatisch example.com noch a.ha.example.com ab.
Bei Cloudflare solltest du die Verbindung zum Origin nicht mit dem unsicheren Modus Flexible erzwingen. Ein HTTPS-Redirect am Origin zusammen mit einem HTTP-Origin-Aufruf kann sonst einen Redirect-Loop verursachen. Prüfe stattdessen die korrekte TLS-Verbindung und die tatsächliche Origin-Service-URL. DNS-01 benötigt einen entsprechend eingeschränkten API-Token; veröffentliche ihn niemals in Screenshots oder Blogbeiträgen.
9. Häufige Fehler und ihre Diagnose
502 Bad Gateway oder 504 Gateway Timeout
Prüfe zuerst, ob die Site online ist, der Connector die interne Ziel-IP erreichen kann und der Zielport stimmt. 502 deutet häufig auf eine nicht erreichbare oder fehlerhaft antwortende Upstream-Verbindung hin, 504 häufig auf ein Timeout. Ein einfacher Test vom Connector-Host ist curl -I http://192.168.1.50:8123; das Schema hängt von deinem Dienst ab.
404 Not Found bei einer neuen Subdomain
Die DNS-Auflösung allein erstellt noch keine Ressource. Prüfe in Pangolin Domain, Ressourcen-Hostnamen und Ziel. Prüfe außerdem, ob ein vorgeschalteter Cloudflare Tunnel den Hostnamen an einen anderen Reverse Proxy weiterleitet.
Zertifikat bleibt pending oder Browser meldet unsicher
Vergleiche öffentliche DNS-Auflösung, offene Ports, tatsächlich zuständigen Reverse Proxy und ACME-Verfahren. Für HTTP-01 muss die HTTP-Challenge den dafür zuständigen Proxy erreichen. Für Wildcard-Zertifikate muss DNS-01 funktionieren. Prüfe Logs, bevor du einen Resolver mehrfach neu startest.
Docker-Container startet nicht
cd ~/pangolin-install
sudo docker compose ps
sudo docker compose logs --tail=150 pangolin
sudo docker compose logs --tail=150 traefik
sudo ss -lntup | grep -E ":(80|443)\b"10. Sicherheits- und Backup-Checkliste
- Verwaltungsoberfläche mit MFA/SSO schützen, sensible Ressourcen nicht versehentlich auf „öffentlich ohne Anmeldung“ stellen.
- Den gesamten Pangolin-Konfigurationsordner samt Datenbank und Schlüsseln regelmäßig verschlüsselt sichern; Restore testen.
- Docker-Images und das Gateway regelmäßig nach offiziellen Release Notes aktualisieren.
- Nur benötigte Ports öffnen, Logs überwachen und die echte Client-IP hinter vorgeschalteten Proxys korrekt behandeln.
- Auf Produktivsystemen Änderungen an Proxy, Zertifikaten und DNS zuerst im Testsystem prüfen.
FAQ
Brauche ich eine Portfreigabe am Heimrouter?
Für den typischen Site-Connector baut dein Heimnetz die Verbindung zum öffentlichen Pangolin-Gateway auf. Deshalb benötigst du meist keine eingehende Portfreigabe zum Homeserver. Die notwendigen Ports müssen jedoch am Pangolin-Gateway erreichbar sein.
Reicht ein einziger *.example.com-DNS-Eintrag für alle Apps?
Für die Namensauflösung vieler Subdomains zum selben Gateway häufig ja. Jede Anwendung benötigt trotzdem ihre eigene Pangolin-Route beziehungsweise eine definierte Wildcard-Routing-Regel. DNS allein entscheidet nicht über das Ziel im Heimnetz.
Kann ich Pangolin zusammen mit Coolify nutzen?
Ja, besonders auf getrennten Servern oder mit einem bewusst gestalteten gemeinsamen Reverse-Proxy-Einstieg. Auf einem Host darf aber nicht gleichzeitig sowohl Pangolin als auch Coolifys Proxy dieselben TCP-Ports 80/443 exklusiv beanspruchen.
Passende weiterführende Anleitungen
- Coolify installieren – Docker-Anwendungen und eigene Domain
- GeoMetrikks installieren – Pangolin- und Traefik-Logs
- Wildcard-DNS: *.domain.de, Cloudflare und Zertifikate
Schreiben Sie einen Kommentar