Exposer un VirtualHost local en permanence avec ngrok

 

Le problème : accéder à un site local depuis l'extérieur

Quand on développe avec un serveur Apache local — Virtualmin sur Proxmox, WAMP, Laragon, peu importe — on se retrouve souvent à vouloir accéder à un site depuis l'extérieur : tester un webhook, partager une démo à un client, ou simplement travailler depuis un autre endroit sans VPN.

La solution classique ? ngrok. Cet outil crée un tunnel sécurisé entre votre machine locale et un domaine public accessible depuis n'importe où. Mais par défaut, ngrok se lance manuellement, dans un terminal, et le tunnel disparaît dès que vous fermez la session. Pas très pratique.

Dans cet article, on va voir comment rendre ce tunnel permanent grâce à un service systemd, et comment réécrire le header Host via la nouvelle Traffic Policy v3 pour que Apache serve le bon VirtualHost.

---

Prérequis

• Un serveur Linux (ici : Ubuntu/Debian sur une VM Proxmox avec Virtualmin)
• Un compte ngrok gratuit avec un domaine statique (ngrok-free.dev)
• Apache avec un VirtualHost configuré sur un nom de domaine .loc (résolution DNS locale)

---

Étape 1 : Installer ngrok

Si ngrok n'est pas encore installé sur votre serveur :

curl -sSL https://ngrok-agent.s3.amazonaws.com/ngrok.asc \
  | sudo tee /etc/apt/trusted.gpg.d/ngrok.asc >/dev/null \
  && echo "deb https://ngrok-agent.s3.amazonaws.com buster main" \
  | sudo tee /etc/apt/sources.list.d/ngrok.list \
  && sudo apt update && sudo apt install ngrok

Ensuite, configurez votre authtoken (disponible sur dashboard.ngrok.com) :

ngrok config add-authtoken VOTRE_AUTHTOKEN

---

Étape 2 : Créer le fichier de configuration ngrok v3

Plutôt que de passer tous les arguments en ligne de commande, on centralise la configuration dans un fichier dédié. Créez le dossier et le fichier :

sudo mkdir -p /etc/ngrok
sudo nano /etc/ngrok/ngrok.yml

Voici la configuration complète au format v3 (le format v2 est déprécié et sera supprimé) :

version: 3

agent:
  authtoken: VOTRE_AUTHTOKEN

endpoints:
  - name: monsite
    url: https://mon-domaine-statique.ngrok-free.dev
    upstream:
      url: http://192.168.0.19:80
    traffic_policy:
      on_http_request:
        - actions:
            - type: add-headers
              config:
                headers:
                  host: "api.monsite.loc"

Pourquoi la Traffic Policy ?

Le problème vient du header Host. Quand une requête arrive via ngrok, Apache reçoit un header Host: mon-domaine-statique.ngrok-free.dev. Or, votre VirtualHost est configuré pour répondre à api.monsite.loc. Résultat : Apache ne reconnaît pas le domaine et sert le mauvais VirtualHost (souvent le site par défaut).

La Traffic Policy de ngrok permet d'intercepter la requête avant qu'elle n'atteigne votre serveur et de réécrire le header Host. L'action add-headers avec la clé host est un cas spécial : elle remplace le header existant plutôt que d'en ajouter un second. Apache reçoit alors Host: api.monsite.loc et sert exactement le bon VirtualHost.

---

Étape 3 : Créer le service systemd

C'est la pièce centrale pour rendre le tunnel permanent. Créez le fichier de service :

sudo nano /etc/systemd/system/ngrok.service

Contenu :

[Unit]
Description=ngrok tunnel permanent
After=network.target

[Service]
Type=simple
ExecStart=/usr/local/bin/ngrok start --all --config /etc/ngrok/ngrok.yml
Restart=on-failure
RestartSec=5
StandardOutput=journal
StandardError=journal

[Install]
WantedBy=multi-user.target

Quelques points importants sur cette configuration :

• After=network.target : ngrok ne démarre qu'une fois la connectivité réseau disponible
• Restart=on-failure : en cas de crash ou de coupure réseau, systemd redémarre automatiquement le processus
• RestartSec=5 : on attend 5 secondes avant de redémarrer, pour éviter une boucle trop rapide
• Les logs sont redirigés vers journald, ce qui permet de les consulter avec journalctl

---

Étape 4 : Activer et démarrer le service

sudo systemctl daemon-reload
sudo systemctl enable ngrok   # Démarrage automatique au boot
sudo systemctl start ngrok    # Démarrage immédiat

---

Vérification

Contrôlez que le service tourne correctement :

sudo systemctl status ngrok

Consultez les logs en temps réel :

sudo journalctl -u ngrok -f

ngrok expose également une interface web locale pour inspecter le trafic en temps réel :

http://127.0.0.1:4040

Vous y verrez toutes les requêtes entrantes, les headers, les réponses, et l'état du tunnel. Très utile pour déboguer.

---

Points d'attention

Compte Free : ngrok gratuit n'autorise qu'une seule session simultanée. Si vous lancez ngrok manuellement ailleurs, cela coupera le service systemd. Veillez à ne jamais avoir deux instances actives en même temps.

Domaine statique : Sur le plan gratuit, ngrok propose un domaine statique gratuit (*.ngrok-free.dev). Sans cela, le domaine change à chaque redémarrage du tunnel, ce qui rend l'approche permanente inutile. Vérifiez que votre domaine statique est bien activé dans le dashboard ngrok.

Sécurité : l'authtoken dans /etc/ngrok/ngrok.yml doit être protégé. Assurez-vous que les permissions du fichier sont correctes :

sudo chmod 600 /etc/ngrok/ngrok.yml
sudo chown root:root /etc/ngrok/ngrok.yml

---

Conclusion

Avec cette configuration, votre tunnel ngrok démarre automatiquement au boot du serveur, redémarre en cas de problème, et réécrit correctement le header Host pour que Apache serve le bon VirtualHost. Une solution propre, sans modifier votre configuration Apache, et entièrement gérée par systemd.

C'est particulièrement utile dans un contexte de homelab ou de développement avec Virtualmin, où on jongle avec de nombreux VirtualHosts locaux qu'on souhaite parfois exposer temporairement — ou de manière continue — vers l'extérieur.