Pangolin sur VPS : exposer un service derrière NAT sans port

Le problème : exposer un service derrière NAT

Ce que Pangolin apporte face aux alternatives

• Self-hosted complet — vos flux transitent par votre VPS uniquement, aucun tiers ne voit votre trafic applicatif.
• Pas d'ouverture de port entrant — la connexion est initiée depuis la machine d'origine vers le VPS (sens sortant), le NAT n'est jamais un obstacle.
• HTTPS automatique via Let's Encrypt — Pangolin gère les certificats pour chaque sous-domaine exposé, sans intervention manuelle.
• Interface web intégrée — ajout de tunnels, gestion des ressources et des utilisateurs depuis un panneau web, sans éditer de fichiers de configuration.
• Chiffrement de bout en bout WireGuard — le tunnel entre la machine d'origine et le VPS est chiffré au niveau transport, indépendamment du HTTPS applicatif.
• Multisite — un seul Pangolin sur le VPS peut relayer des dizaines de services depuis des machines différentes, sous des sous-domaines distincts.

Architecture : VPS relay, Gerbil et Newt

[Machine d'origine]                [VPS ServOrbit]              [Internet]
  service:8080                      Pangolin (orchestration)
  newt (client)  ←─WireGuard UDP─→  Gerbil  (tunnel WG)   ←─HTTPS──→  visiteur
                                    Traefik (reverse proxy)

Prérequis

Déploiement de Pangolin et Gerbil sur le VPS

1. 01

   Préparer le VPS et ouvrir le port WireGuard

   Connectez-vous en root sur le VPS et installez Docker s'il n'est pas déjà présent :

   apt update && apt install -y docker.io docker-compose-plugin ufw

   Ouvrez le port UDP pour WireGuard (51820 par défaut) et assurez-vous que les ports HTTP/HTTPS sont accessibles :

   ufw allow 80/tcp
   ufw allow 443/tcp
   ufw allow 51820/udp
   ufw enable

   Si vous souhaitez restreindre l'accès au panneau d'administration (port 3000 par défaut), limitez-le à votre IP :

   ufw allow from VOTRE_IP to any port 3000

2. 02

   Créer le fichier docker-compose.yml

   Créez un dossier de travail et le fichier de configuration :

   mkdir -p /opt/pangolin && cd /opt/pangolin

   Créez docker-compose.yml avec le contenu suivant :

   cat > docker-compose.yml <<'EOF'
   services:
     pangolin:
       image: fosrl/pangolin:1.23.0
       container_name: pangolin
       restart: unless-stopped
       volumes:
         - ./config:/app/config
         - ./data:/app/data
       ports:
         - "3000:3000"
       networks:
         - pangolin_net
   
     gerbil:
       image: fosrl/gerbil:latest
       container_name: gerbil
       restart: unless-stopped
       cap_add:
         - NET_ADMIN
       volumes:
         - ./data:/var/lib/gerbil
       ports:
         - "51820:51820/udp"
       networks:
         - pangolin_net
       depends_on:
         - pangolin
   
   networks:
     pangolin_net:
       driver: bridge
   EOF

   Adaptez le numéro de version de l'image pangolin à la dernière release disponible sur GitHub.

3. 03

   Configurer Pangolin et démarrer la stack

   Créez le dossier de configuration et un fichier config.yml minimal :

   mkdir -p /opt/pangolin/config
   cat > /opt/pangolin/config/config.yml <<'EOF'
   app:
     base_domain: mondomaine.com
     admin_email: [email protected]
     port: 3000
   
   wireguard:
     port: 51820
     subnet: 10.0.0.0/24
   
   acme:
     enabled: true
     staging: false
   EOF

   Remplacez mondomaine.com par votre domaine réel. Démarrez la stack :

   cd /opt/pangolin && docker compose up -d
   docker compose logs -f pangolin

   Pangolin génère un mot de passe administrateur au premier démarrage — notez-le depuis les logs. L'interface web est accessible sur http://IP_VPS:3000.

4. 04

   Configurer le DNS wildcard

   Dans votre zone DNS, créez un enregistrement A wildcard pointant vers l'IP du VPS :

   *.mondomaine.com  →  A  →  IP_VPS

   Sur Cloudflare, créez ce même enregistrement avec le proxy désactivé (DNS-only, nuage gris) pour que les certificats Let's Encrypt puissent être émis correctement via le défi HTTP-01 utilisé par Pangolin.

5. 05

   Créer une unité systemd pour le redémarrage automatique

   Docker avec restart: unless-stopped suffit généralement, mais si vous préférez une unité systemd dédiée :

   cat > /etc/systemd/system/pangolin.service <<'EOF'
   [Unit]
   Description=Pangolin reverse tunnel stack
   After=docker.service
   Requires=docker.service
   
   [Service]
   Type=oneshot
   RemainAfterExit=yes
   WorkingDirectory=/opt/pangolin
   ExecStart=/usr/bin/docker compose up -d
   ExecStop=/usr/bin/docker compose down
   
   [Install]
   WantedBy=multi-user.target
   EOF
   
   systemctl daemon-reload
   systemctl enable pangolin

Ajout d'un tunnel avec Newt sur la machine d'origine

1. 06

   Créer un tunnel dans l'interface Pangolin

   Connectez-vous à l'interface web Pangolin sur http://IP_VPS:3000 avec les identifiants admin. Allez dans Sites → Ajouter un site, donnez-lui un nom (ex. homelab) et notez le token de site généré. Puis dans Ressources → Ajouter une ressource, choisissez le site, saisissez le sous-domaine souhaité (nextcloud.mondomaine.com) et le port local de la machine d'origine (ex. 8080).

2. 07

   Installer Newt sur la machine d'origine

   Sur la machine qui héberge votre service, téléchargez le binaire Newt correspondant à votre architecture :

   # Sur Linux x86_64
   curl -Lo /usr/local/bin/newt \
     https://github.com/fosrl/newt/releases/latest/download/newt-linux-amd64
   chmod +x /usr/local/bin/newt

   Pour un Raspberry Pi (ARM64) :

   curl -Lo /usr/local/bin/newt \
     https://github.com/fosrl/newt/releases/latest/download/newt-linux-arm64
   chmod +x /usr/local/bin/newt

3. 08

   Configurer et démarrer Newt

   Lancez Newt avec le token de site récupéré à l'étape précédente :

   newt \
     --server https://mondomaine.com:3000 \
     --token VOTRE_TOKEN_DE_SITE \
     --target localhost:8080

   Pour un démarrage automatique, créez une unité systemd :

   cat > /etc/systemd/system/newt.service <<'EOF'
   [Unit]
   Description=Newt WireGuard tunnel client
   After=network.target
   
   [Service]
   ExecStart=/usr/local/bin/newt \
     --server https://mondomaine.com:3000 \
     --token VOTRE_TOKEN_DE_SITE \
     --target localhost:8080
   Restart=always
   RestartSec=5
   
   [Install]
   WantedBy=multi-user.target
   EOF
   
   systemctl daemon-reload
   systemctl enable --now newt

4. 09

   Vérifier la connectivité end-to-end

   Sur le VPS, vérifiez que le tunnel WireGuard est établi :

   docker exec gerbil wg show

   Vous devriez voir un peer avec un latest handshake récent. Depuis n'importe quel navigateur ou en ligne de commande :

   curl -I https://nextcloud.mondomaine.com

   Réponse attendue : HTTP/2 200 (ou la page de connexion de votre service). Le certificat Let's Encrypt est émis automatiquement au premier accès.

Exposition d'un service : exemple Nextcloud derrière NAT

1. 10

   Configurer Nextcloud pour accepter le domaine proxy

   Nextcloud bloque les requêtes venant de domaines non déclarés. Ajoutez le domaine public à config.php :

   # Depuis la machine d'origine, dans le dossier Nextcloud
   nano config/config.php

   Ajoutez dans le tableau trusted_domains :

   'trusted_domains' =>
     array (
       0 => 'localhost',
       1 => 'nextcloud.mondomaine.com',
     ),
   'overwritehost' => 'nextcloud.mondomaine.com',
   'overwriteprotocol' => 'https',

2. 11

   Vérifier l'accès public et le certificat

   Attendez 30 à 60 secondes après le premier accès pour que Let's Encrypt émette le certificat, puis :

   curl -v https://nextcloud.mondomaine.com 2>&1 | grep -E 'subject|issuer|HTTP'

   Le certificat est signé par Let's Encrypt et l'URL publique est désormais accessible depuis n'importe quel réseau, sans aucun port ouvert côté réseau local.

Dépannage

Pangolin vs Cloudflare Tunnel vs Tailscale/Headscale

Faites défiler le tableau

Aller plus loin