Guide de configuration du proxy inversé Ngrok dans ServBay

Ngrok est un outil de tunnel sécurisé et puissant, basé sur la technologie de proxy inversé. Il permet de traverser les pare-feu et le NAT pour mapper les services exécutés en local sur un nom de domaine accessible publiquement. Ce guide vous explique en détail comment intégrer et configurer Ngrok dans votre environnement de développement local ServBay, afin de rendre vos services Web, API ou autres accessibles depuis Internet. Cela facilite les démonstrations à distance, le travail collaboratif en équipe ou les tests de callbacks de services tiers.

Principe technique

Le principe fondamental de Ngrok consiste à établir un tunnel chiffré entre votre machine locale et les serveurs Ngrok. Lorsqu’un utilisateur externe accède à votre service via un nom de domaine public attribué par Ngrok, la requête arrive d’abord sur les serveurs Ngrok, puis est transmise par ce tunnel sécurisé vers le service correspondant exécuté dans votre environnement local ServBay. Ainsi, même si votre machine locale ne possède pas d’IP publique ou se trouve derrière un pare-feu, elle peut rendre ses services accessibles de l’extérieur. Dans le contexte de ServBay, cela vous permet de partager en temps réel vos sites Web, APIs ou tout autre service HTTP/HTTPS hébergé localement pour des tests et des présentations externes.

Préparation de l’environnement

Avant de commencer la configuration de Ngrok, assurez-vous d'avoir terminé les étapes suivantes :

1. ServBay est installé et en cours d’exécution : Vérifiez que l'application ServBay est correctement installée et que le service Web que vous souhaitez exposer via Ngrok (par exemple un site Web) est bien configuré et fonctionnel dans ServBay. Vous pouvez gérer vos sites locaux dans le panneau “Sites” de ServBay.
2. Installation du client Ngrok : Installez l’outil CLI Ngrok en suivant ces étapes :
   1. Rendez-vous sur la page officielle de téléchargement de Ngrok pour obtenir le package adapté à votre système d’exploitation.
   2. Décompressez l’archive téléchargée. Déplacez ou copiez ensuite l’exécutable ngrok dans un dossier inclus dans le PATH du système (sur macOS, typiquement /usr/local/bin) pour pouvoir utiliser la commande ngrok dans n’importe quel terminal.

      # Exemple pour l’architecture ARM64 sur macOS
      sudo unzip ~/Downloads/ngrok-v3-stable-darwin-arm64.zip -d /usr/local/bin

   3. Vérifiez l’installation en exécutant la commande ngrok version et en confirmant l’affichage du numéro de version :

      ngrok version
      # Exemple de résultat : ngrok version 3.5.0

3. Compte Ngrok (facultatif mais recommandé) : Disposer d’un compte Ngrok (gratuit ou payant) facilite la gestion des tunnels et l’utilisation de fonctionnalités avancées comme un domaine fixe. Inscrivez-vous sur le site Ngrok et récupérez votre jeton d’authentification (ngrok config add-authtoken <VOTRE_JETON_AUTH>) pour lever les limitations de durée de session et accéder à des fonctionnalités avancées.
4. Site local déjà configuré : Vous devez avoir au moins un site local configuré dans ServBay que vous souhaitez exposer via Ngrok, par exemple avec le domaine servbay.local ou yourproject.servbay.demo pour un accès local.

Pratique de la configuration des tunnels

Explication des principaux paramètres

La commande standard pour mapper un service local à un domaine public via Ngrok s’écrit ainsi :

ngrok http --domain=<NGROK_DOMAIN> <LOCAL_ENDPOINT> \
  --request-header-add='host: <VIRTUAL_HOST>'

Élément du paramètre	Description
http	Spécifie la création d’un tunnel basé sur le protocole HTTP. Ngrok prendra en charge les requêtes HTTP/HTTPS entrantes.
--domain <NGROK_DOMAIN>	Définit le domaine fixe attribué par Ngrok (remplacez-le par votre nom de domaine configuré depuis le Dashboard de Ngrok). Pour les comptes gratuits, ce paramètre n’est généralement pas nécessaire : un sous-domaine aléatoire sera attribué automatiquement.
<LOCAL_ENDPOINT>	Adresse locale du service ServBay. Pour un hôte virtuel ServBay, il s’agit généralement du domaine local (https://servbay.local), ou encore http://localhost:port.
--request-header-add='host: <VIRTUAL_HOST>'	【Important】 Modifie l’en-tête Host de la requête. ServBay distingue ses sites via l’en-tête HTTP Host. Ce paramètre permet de remplacer celui des connexions extérieures par le domaine local du site virtuel (ex : servbay.local), assurant l’acheminement correct vers le bon site dans ServBay.

Exemple de configuration

Supposons que vous ayez configuré un site local dans ServBay avec le domaine servbay.local et que vous souhaitiez l’exposer publiquement via Ngrok. Si vous utilisez le compte gratuit, il suffit de mapper l’adresse locale :

# Mapper le site ServBay local servbay.local vers un domaine public généré aléatoirement par Ngrok
ngrok http https://servbay.local --request-header-add='host: servbay.local'

Si vous possédez un domaine fixe configuré dans le Dashboard Ngrok, du type your-servbay-demo.ngrok-free.app ou un domaine personnalisé payant, utilisez le paramètre --domain :

# Mapper le site ServBay servbay.local vers un domaine spécifique attribué par Ngrok
ngrok http --domain=your-servbay-demo.ngrok-free.app https://servbay.local --request-header-add='host: servbay.local'

Après exécution, le client Ngrok affiche dans le terminal le statut du tunnel, dont l’adresse publique attribuée (ex : https://xxxx.ngrok-free.app ou votre domaine personnalisé) et l’adresse du tableau de bord local de suivi du trafic (généralement http://127.0.0.1:4040).

Vérification du service

Une fois la configuration terminée et le tunnel Ngrok lancé, procédez comme suit pour vérifier l’accessibilité publique de votre service :

1. Récupérer l’adresse publique : Repérez la ligne Forwarding dans la fenêtre terminal du client Ngrok ; notez l’URL publique débutant par https://.
2. Accès depuis un navigateur : Sur n’importe quel appareil connecté à Internet, ouvrez l’URL publique Ngrok dans un navigateur web (par exemple https://cunning-lacewing-fresh.ngrok-free.app ou votre domaine fixe).
3. Vérification :
   • Assurez-vous que le contenu de votre site, hébergé sur ServBay, se charge correctement dans le navigateur.
   • Vérifiez que la barre d’adresse indique une connexion HTTPS sécurisée. Ngrok fournit par défaut un certificat SSL valide pour le tunnel.
   • Consultez les journaux de requêtes et les statistiques de trafic dans le terminal du client Ngrok ou via son interface Web locale (http://127.0.0.1:4040) pour confirmer la bonne réception/traitement des requêtes par ServBay.

Illustration : accès réussi au tunnel créé par Ngrok via un navigateur Web

Astuces avancées et points d'attention

1. Gestion des domaines :
   • Avec le plan gratuit Ngrok, un sous-domaine .ngrok-free.app aléatoire est attribué, et les tunnels sont soumis à des limites de durée.
   • Créez un compte Ngrok et utilisez le Dashboard Ngrok pour réserver un domaine fixe et éviter que l’URL publique ne change à chaque lancement du tunnel.
   • Les plans payants de Ngrok permettent d’utiliser vos propres domaines, avec plus de bande passante, de connexions simultanées et de fonctionnalités avancées.
2. Mapper plusieurs services : Pour exposer plusieurs services locaux ou ports de ServBay sur Internet, vous pouvez lancer plusieurs processus Ngrok ou définir plusieurs tunnels dans le fichier de configuration Ngrok (~/.config/ngrok/ngrok.yml). Par exemple, pour mapper un site ServBay et un service Node.js local :

   # Mapper servbay.local (via HTTPS 443 et routage par en-tête Host)
   ngrok http --domain=servbay-website.ngrok-free.app https://servbay.local --request-header-add='host: servbay.local'
   
   # Dans un autre terminal ou via la config, mapper une app Node.js locale sur le port 3000
   ngrok http --domain=nodejs-api.ngrok-free.app http://localhost:3000

   Remarque : Pour les hôtes virtuels ServBay, il est recommandé d’utiliser https://[domaine_local] avec l’option --request-header-add plutôt que de pointer directement vers les ports 80/443 de ServBay, car celui-ci gère toutes les requêtes de ses hôtes virtuels sur ces ports.
3. Commandes de diagnostic :
   • ngrok config check : Vérifie la syntaxe du fichier de configuration (~/.config/ngrok/ngrok.yml).
   • ngrok logs : Affiche en temps réel les logs détaillés du client Ngrok pour diagnostiquer toute anomalie de connexion ou d’acheminement des requêtes.
4. Sécurité : Exposer un service local au public implique des risques de sécurité. Veillez à sécuriser les services exposés et à n’exécuter un tunnel Ngrok que lorsque cela est nécessaire. Les offres payantes de Ngrok proposent la whitelist IP, les restrictions d'accès et d’autres mécanismes de sécurité.

Dépannage

Problème	Solution
Délai de connexion ou page qui ne charge pas	Vérifiez que le site cible ServBay est actif et accessible localement (ex : via https://servbay.local). Contrôlez le fonctionnement du serveur Web de ServBay (Caddy ou Nginx). Vérifiez également que votre pare-feu local autorise le client Ngrok à se connecter à Internet.
Erreur de certificat HTTPS (alerte navigateur)	Ngrok fournit un certificat HTTPS valide pour chaque domaine public alloué. Si un problème de certificat survient à l'accès d’un domaine Ngrok, il s'agit le plus souvent d’un souci de configuration Ngrok ou du réseau, pas de ServBay. Vérifiez bien que l’URL publique utilisée commence par https://. Si l’erreur apparaît sur le domaine local ServBay, vérifiez la configuration SSL de ServBay.
Coupures ou lenteurs intermittentes	Vérifiez la stabilité de votre connexion locale à Internet (un réseau fluctuant peut interrompre le tunnel). Privilégiez une connexion filaire pour plus de stabilité, ou souscrivez à une offre payante pour accroitre la fiabilité et la bande passante.
Affichage de la page par défaut de ServBay au lieu du site voulu	Vérifiez que l’adresse locale <LOCAL_ENDPOINT> dans la commande ngrok http est correcte et que l’option --request-header-add='host: <VIRTUAL_HOST>' correspond exactement au domaine du site local défini dans ServBay. Ceci est essentiel pour assurer un bon routage de la requête.

FAQ (Foire aux questions)

• Q : Peut-on exposer un service de base de données ServBay ?

  R : Ngrok est principalement destiné aux tunnels HTTP/HTTPS. Il prend aussi en charge les tunnels TCP (pour les bases de données, etc.), mais cela dépasse le cadre du présent guide orienté HTTP, et il est généralement déconseillé d’exposer une base de données locale sur Internet pour des raisons de sécurité. Préférez l’utilisation d’un tunnel SSH ou d’autres solutions plus sûres pour l'accès distant aux bases de données.

• Q : À chaque démarrage, l’URL publique Ngrok change-t-elle ?

  R : Pour les comptes gratuits, un sous-domaine aléatoire .ngrok-free.app est en effet généré à chaque session. Pour obtenir un domaine public fixe, il faudra enregistrer un compte et configurer le domaine depuis le Dashboard, voire souscrire à un plan payant.

• Q : Ngrok impacte-t-il les performances de ServBay ?

  R : L’usage de Ngrok induit une légère latence supplémentaire puisque les requêtes transitent par les serveurs Ngrok. Toutefois, pour les usages de développement, test ou démonstration, cette latence reste généralement négligeable. Les performances du service hébergé dépendent en premier lieu de la puissance de votre machine et de l’efficacité de votre site/application.

Conclusion

Grâce à l’intégration de Ngrok, les utilisateurs de ServBay peuvent facilement, de façon sécurisée et efficace, partager leur travail de développement Web local sur Internet. Ce procédé ne nécessite aucune configuration réseau complexe et se prête particulièrement bien aux collaborations à distance, démonstrations client, tests mobiles ou interfaçages avec des services tiers. Ngrok propose un suivi temps réel du trafic et de nombreux mécanismes de sécurité (certaines options avec abonnement). Pour les usages critiques ou nécessitant des domaines fixes, il est recommandé d’opter pour un forfait payant Ngrok afin de bénéficier d’une expérience plus stable et de fonctionnalités avancées.