Trace install tas - ngrok

Rôle et état

ngrok fournit un tunnel HTTPS public vers un service HTTP local de tas. L'instance documentée expose temporairement le point d'entrée Caddy local du tunnel, sur le port 8099, vers un domaine fixe ngrok.

État vérifié le 22 août 2026 :

binaire : /usr/local/bin/ngrok ;
version : 3.39.11 ;
domaine fixe : https://noella-oxidizable-nonsuppositively.ngrok-free.dev ;
cible locale ngrok : 8099 ;
service systemd utilisateur : ngrok-8080.service ;
service : actif et activé au démarrage de la session utilisateur.

Le nom historique ngrok-8080.service est conservé, mais la cible actuelle est le port 8099, et non le port 8080.

Mise en œuvre

ngrok n'est pas exécuté dans un conteneur. Le binaire est installé sur l'hôte et lancé sous le compte utilisateur loic par systemd utilisateur.

La commande exécutée par le service est :

/usr/local/bin/ngrok http --url=https://noella-oxidizable-nonsuppositively.ngrok-free.dev 8099 --config /home/loic/.config/ngrok/ngrok.yml

L'installation initiale du paquet a utilisé le dépôt officiel ngrok :

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 bookworm main" | sudo tee /etc/apt/sources.list.d/ngrok.list
sudo apt update
sudo apt install ngrok

Le jeton d'authentification n'est pas documenté ici. Il est conservé dans le fichier protégé /home/loic/.config/ngrok/ngrok.yml, dont les permissions attendues sont 0600 et le propriétaire loic.

Routage local

Le tunnel ngrok vise Caddy, pas directement l'application finale :

Internet → domaine ngrok fixe → ngrok → 127.0.0.1:8099 → Caddy → 127.0.0.1:8085

Le bloc Caddy correspondant est dans /etc/caddy/Caddyfile :

:8099 {
    reverse_proxy 127.0.0.1:8085
}

Cette chaîne permet notamment de conserver le tunnel lorsque le service Open WebUI change de port interne, sous réserve d'adapter le backend Caddy.

Mode d'automatisation

L'automatisation repose exclusivement sur l'unité systemd utilisateur :

/home/loic/.config/systemd/user/ngrok-8080.service

Caractéristiques :

After=network-online.target et Wants=network-online.target ;
Type=simple ;
Restart=always ;
RestartSec=5 ;
WantedBy=default.target.

Il n'y a pas de cron, de timer systemd, de Quadlet ni de conteneur ngrok pour ce tunnel.

Démarrage

Démarrer le tunnel :

systemctl --user start ngrok-8080.service

Activer le démarrage automatique :

systemctl --user enable ngrok-8080.service

Après modification de l'unité :

systemctl --user daemon-reload
systemctl --user restart ngrok-8080.service

Arrêt et redémarrage

Arrêter le tunnel sans supprimer la configuration :

systemctl --user stop ngrok-8080.service

Empêcher son redémarrage à la prochaine session utilisateur :

systemctl --user disable ngrok-8080.service

Redémarrer le tunnel :

systemctl --user restart ngrok-8080.service

Ces opérations ne suppriment ni le binaire, ni le fichier de configuration, ni le domaine réservé.

Contrôles et journaux

systemctl --user status ngrok-8080.service
systemctl --user is-enabled ngrok-8080.service
systemctl --user is-active ngrok-8080.service
journalctl --user -u ngrok-8080.service -n 100 --no-pager
ngrok version
curl -I https://noella-oxidizable-nonsuppositively.ngrok-free.dev

En cas d'échec, vérifier d'abord que Caddy écoute bien sur 8099 et que son backend 127.0.0.1:8085 répond avant de relancer ngrok.

Retour arrière

Le retour arrière courant consiste à arrêter et désactiver le service :

systemctl --user disable --now ngrok-8080.service

Ne pas supprimer le fichier /home/loic/.config/ngrok/ngrok.yml pendant cette opération. La configuration peut ainsi être réactivée sans réinstallation.

Fichiers de référence

/usr/local/bin/ngrok
/home/loic/.config/ngrok/ngrok.yml — secret, ne pas publier ;
/home/loic/.config/systemd/user/ngrok-8080.service
/etc/caddy/Caddyfile — bloc :8099.