Serveur autonome

Le serveur autonome fait tourner Runlight comme une application à part entière pour autant de sites que vous voulez, avec une connexion, des liens courts sur vos propres domaines et des rapports par e-mail.

Le serveur autonome, c’est Runlight empaqueté comme une application à part entière. Il convient à un site dont l’application ne peut pas faire tourner Runlight, et il donne un seul tableau de bord à plusieurs sites. Il exécute le même code que la bibliothèque, donc les rapports, les objectifs, les liens courts et les rapports par e-mail fonctionnent tous de la même façon.

Cette page traite du serveur Node. Python, Ruby, Go, Java et .NET ont chacun leur propre serveur qui fonctionne de la même façon, et sur un hébergement qui fait tourner PHP sans Node, le drop-in PHP fait le même travail.

Le démarrer

Avec Docker, lancez ceci.

docker run -d --name runlight -p 3000:3000 -v runlight:/data ghcr.io/runlightsh/runlight

Quand un proxy sur la même machine ajoute HTTPS, comme dans Le mettre sur Internet, publiez le port uniquement sur l’adresse de loopback, avec -p 127.0.0.1:3000:3000. Docker ouvre un port publié en passant outre les pare-feu comme ufw, et un client qui atteint directement le port en clair peut nommer n’importe quel hôte et envoyer une fausse adresse transmise.

Avec Node 22 ou plus récent, lancez plutôt ceci.

npx runlight.sh

Le serveur écoute sur le port 3000. Il garde ses données dans un dossier nommé runlight-data dans le répertoire depuis lequel vous le lancez, ou dans /data dans Docker.

Créer votre compte

À son premier démarrage, le serveur affiche dans son journal un lien de configuration avec un code à usage unique. Ouvrez ce lien et saisissez votre adresse e-mail et un mot de passe d’au moins dix caractères, tapé deux fois pour qu’une faute de frappe ne puisse pas vous bloquer. Le lien ne fonctionne que tant que le serveur n’a aucun compte, donc personne qui tomberait le premier sur un nouveau serveur ne peut se l’approprier.

Dans Docker, c’est dans le journal qu’il faut regarder.

docker logs runlight

Le lien commence par http://localhost:3000. Quand le serveur tourne ailleurs, gardez tout à partir de /setup et mettez devant l’adresse du serveur, par exemple https://stats.example.com/setup?code=.... Chaque démarrage crée un nouveau code, donc après un redémarrage, utilisez le lien des lignes les plus récentes du journal.

La personne qui configure le serveur en est le propriétaire. Le propriétaire et les administrateurs invitent des personnes dans Réglages, Personnes, comme administrateur, membre ou lecteur.

Le propriétaire peut transmettre la propriété à un administrateur avec Rendre propriétaire dans Réglages, Personnes, après avoir saisi son mot de passe, et devient alors administrateur. L’invitation part par e-mail quand le serveur a un service d’e-mail (configuré dans Réglages, Service d’e-mail), et le tableau de bord affiche toujours le lien aussi, pour que vous puissiez l’envoyer autrement. La personne l’ouvre, choisit un mot de passe et se retrouve connectée. Un lien fonctionne une fois, pendant sept jours, et Renvoyer en crée un nouveau. Chacun peut changer son mot de passe plus tard dans Compte, en bas du tableau de bord. Un serveur antérieur à ces rôles garde son premier propriétaire comme propriétaire, et les autres propriétaires deviennent administrateurs. Retirer quelqu’un, ou le passer lecteur, supprime aussi les jetons d’API qu’il a créés et les applications qu’il a connectées, comme Claude ou un hub. Les jetons créés avec RUNLIGHT_TOKEN, ou avant cette version, n’ont pas d’auteur enregistré, donc après avoir retiré quelqu’un, vérifiez-les dans Réglages, API et IA.

Connexion à deux facteurs

Chacun peut activer la connexion à deux facteurs dans Compte, en bas du tableau de bord. Confirmez votre mot de passe, scannez le code QR avec une application d’authentification comme 1Password, Google Authenticator ou Authy, et saisissez le code qu’elle affiche. La connexion demande ensuite un code frais après le mot de passe. Vous recevez aussi dix codes de secours, affichés une seule fois, et chacun vous connecte une fois si votre téléphone n’est plus là. Le propriétaire ou un administrateur peut réinitialiser la connexion à deux facteurs de quelqu’un d’autre dans Réglages, Personnes, après avoir saisi son propre mot de passe, mais seul le propriétaire peut changer celle du propriétaire. Activer ou désactiver la connexion à deux facteurs vous déconnecte de tous les autres navigateurs, et celui que vous utilisez reste connecté.

Limites de connexion

Une adresse a droit à dix mots de passe erronés pour un compte toutes les quinze minutes, et le compte à cinquante, d’où qu’ils viennent. Chaque essai est compté à son arrivée, donc une rafale de tentatives envoyées d’un coup ne va pas plus loin. Quand le compte a atteint sa limite, un navigateur qui s’y est déjà connecté entre quand même, et tous les autres essais reçoivent la même réponse, que le mot de passe soit bon ou non. Avec la connexion à deux facteurs, cette réponse est l’étape du code, que seul le ticket d’un bon mot de passe peut franchir, donc vous pouvez toujours entrer depuis un nouveau navigateur. Sans elle, un bon mot de passe vous envoie par e-mail un lien de connexion quand le serveur a un service d’e-mail, et sinon le compte attend quinze minutes. Le lien fonctionne une fois, pendant quinze minutes, et l’utiliser annule tout lien envoyé avant lui. L’étape du code accepte cinq codes erronés toutes les quinze minutes, et la confirmation d’une nouvelle configuration à deux facteurs en accepte cinq avant de devoir tout recommencer. Les compteurs sont gardés en mémoire, avec les adresses IP et les adresses e-mail hachées par une clé créée à chaque démarrage.

Mots de passe oubliés

Si quelqu’un est bloqué, lancez la commande password sur le serveur pour donner au compte un nouveau mot de passe, qu’elle affiche. Elle désactive aussi la connexion à deux facteurs pour ce compte, puisque quelqu’un qui a accès au serveur est bien qui il prétend être. La même commande crée un nouveau compte, propriétaire sur un serveur encore vide et administrateur sinon.

npx runlight.sh password someone@example.com

Dans Docker, lancez la même commande dans le conteneur.

docker exec runlight node node_modules/runlight.sh/dist/cli.js password someone@example.com

Ajouter vos sites

Une fois que vous êtes connecté, le tableau de bord vous demande le domaine de votre premier site. L’écran suivant vous donne la balise script pour les pages de ce site, avec l’adresse du serveur et l’identifiant du site déjà remplis.

<script defer src="https://stats.example.com/s.js?site=example.com" data-site="example.com"></script>

Ajoutez d’autres sites depuis le menu à côté du nom du site. Dans Réglages, Général, vous pouvez changer les domaines, le nom et le fuseau horaire d’un site, ou supprimer le site avec tout ce qui a été enregistré pour lui.

Connecter des sites qui se comptent eux-mêmes

Un site qui a Runlight dans sa propre application peut lui aussi rejoindre ce serveur, pour que tous les sites soient dans un seul tableau de bord. Choisissez Ajouter un site, Connecter un autre Runlight, et saisissez l’adresse Runlight de l’application, par exemple https://example.com/runlight. Votre navigateur ouvre le Runlight de cette application, où vous vous connectez si besoin, choisissez le site et cliquez sur Allow. Vous revenez ici avec le site ajouté.

Les chiffres du site restent dans la base de données de l’application. Ce serveur les lit par l’API de l’application à chaque consultation, donc ils sont toujours à jour. Ses objectifs, entonnoirs, liens courts, domaines de liens, rapports par e-mail, liens de partage et la durée de conservation des visites peuvent tous être modifiés d’ici, et chaque modification est enregistrée dans l’application. Les personnes, les jetons, les imports et le service d’e-mail de l’application restent du côté de l’application. Tous les sites, dans le menu des sites, aligne chaque site côte à côte pour les dates que vous choisissez.

L’application garde l’autorisation sous forme de jeton dans ses Réglages, API et IA, limité à ce seul site. Le supprimer là-bas déconnecte aussitôt ce serveur. Un site connecté avec un jeton en lecture seule avant l’arrivée de ce mécanisme affiche Autoriser les modifications dans ses réglages, qui suit les mêmes étapes. Si l’application supprime ce jeton, Reconnecter dans les réglages du site en crée un nouveau, et déconnecter un site ici supprime son jeton là-bas.

Si l’application fait tourner un Runlight plus ancien que celui-ci, connectez-la plutôt avec un jeton. Créez-en un dans les Réglages, API et IA de l’application, puis choisissez Utiliser plutôt un jeton d’API au moment de la connexion. Un jeton de lecture affiche ici les chiffres du site, et ses réglages restent dans l’application.

Le mettre sur Internet

Le serveur parle en HTTP simple, donc faites-le tourner derrière un proxy qui ajoute HTTPS. Avec Caddy, toute la configuration pour un serveur sur stats.example.com tient en ceci.

stats.example.com {
  reverse_proxy localhost:3000
}

Définissez RUNLIGHT_URL avec l’adresse publique du serveur, par exemple https://stats.example.com. Les liens courts ne peuvent alors jamais s’approprier ce nom, et les e-mails d’invitation et de rapport pointent vers elle, quel que soit l’en-tête Host d’une requête. Un hub connecté n’ajoute des domaines de liens et des rapports par e-mail qu’une fois cette variable définie.

Runlight lit l’adresse de chaque visiteur dans la dernière entrée de X-Forwarded-For, celle qu’ajoute votre proxy. Définissez TRUST_PROXY à x-real-ip ou cf-connecting-ip quand c’est cet en-tête qui contient l’adresse, par exemple derrière Cloudflare et un autre proxy. Définissez TRUST_PROXY=false quand rien ne se trouve devant le serveur, pour qu’un visiteur ne puisse pas envoyer une fausse adresse.

Liens courts sur vos propres domaines

N’importe quel domaine qui pointe vers le serveur peut servir des liens courts à sa racine, sans rien d’autre à installer. Faites pointer le domaine vers le serveur avec un enregistrement CNAME, faites-le accepter par votre proxy avec HTTPS, puis ajoutez-le dans Réglages, Domaines personnalisés. Dans Caddy, cela revient à lister le domaine à côté de celui du serveur.

stats.example.com, go.example.com {
  reverse_proxy localhost:3000
}

Chaque lien répond aussi sur /go/your-slug sur le domaine du serveur. Les pages du serveur, comme /login et tout ce qui se trouve sous /api, répondent aussi en tant que serveur sur un domaine de liens, donc un lien qui porte l’un de ces identifiants ne fonctionne que sur /go/. Un domaine de liens ne peut jamais être l’adresse publique du serveur ni un nom depuis lequel le propriétaire ou un administrateur s’est connecté, et si l’un d’eux a été ajouté ainsi auparavant, se connecter sur /login ouvre toujours le tableau de bord pour que vous puissiez le retirer. Le serveur retient les 20 premiers noms depuis lesquels ils se connectent, donc définissez RUNLIGHT_URL s’il répond sur davantage.

Lieux

Derrière Cloudflare, Runlight prend le pays, la région et la ville de chaque visiteur dans les en-têtes qu’ajoute Cloudflare. Sans eux, le serveur télécharge la base de villes gratuite de DB-IP dans son dossier de données au premier démarrage, et récupère la nouvelle version chaque mois. Le fichier pèse environ 130 Mo et le serveur le garde en mémoire. La licence de DB-IP demande une mention, donc le pied de page du tableau de bord la cite.

Définissez RUNLIGHT_GEO=country pour utiliser la base de pays de DB-IP, plus petite, qui pèse environ 8 Mo et n’a ni régions ni villes. Mettez off pour ne rien chercher, ou le chemin d’un fichier MMDB à vous, comme GeoLite2 City de MaxMind.

Réglages

Le serveur lit ses réglages dans des variables d’environnement.

Rapports par e-mail et vérification planifiée

Le serveur lance lui-même la vérification planifiée de Runlight toutes les cinq minutes, il n’a donc besoin d’aucun cron. Configurez un service d’e-mail dans Réglages, Service d’e-mail, ajoutez qui reçoit les rapports dans Réglages, Rapports par e-mail, et les rapports partent tout seuls.

Sauvegardes et mises à jour

Sauvegardez le dossier de données. Il contient le fichier SQLite et le fichier secret, et sans le secret, les clés enregistrées ne peuvent pas être lues et tout le monde doit se reconnecter. Ce sont celles du service d’e-mail, de l’assistant IA, les jetons des installations connectées et les secrets de connexion à deux facteurs de chacun, donc la connexion à deux facteurs doit aussi être reconfigurée. Pour mettre à jour, récupérez la nouvelle image ou lancez npx runlight.sh@latest, et la base de données se met à jour toute seule au démarrage.

Faire tourner plusieurs copies

Plusieurs copies du serveur peuvent partager une même base Postgres, MySQL ou MariaDB, par exemple derrière un répartiteur de charge. Chaque copie relit la liste des sites et des installations connectées toutes les cinq minutes, donc un site ajouté sur n’importe quelle copie apparaît sur les autres en moins de cinq minutes. Tout le reste, des visites aux objectifs et aux liens, est partagé immédiatement.

Agents IA depuis un journal

Les agents IA comme GPTBot et ClaudeBot récupèrent les pages sans exécuter de JavaScript, donc la balise script ne les voit jamais. Sur un site qui a Runlight dans son application, ou une extension WordPress, Drupal ou Craft, ils sont comptés là où la page est servie. Pour tout autre site que vous hébergez vous-même, le journal d’accès du serveur web les contient, et la commande agents le lit.

npx runlight.sh agents --log /var/log/nginx/access.log --to https://stats.example.com --key rlo_... --site https://example.com --follow

La clé est la clé des agents du site, affichée dans Runlight dans Réglages, Installation, et elle ne peut signaler que les requêtes de ce site. --site est l’adresse du site, pour les journaux au format habituel de nginx ou d’Apache, qui omettent l’hôte. Les journaux JSON de Caddy contiennent l’hôte, donc il n’y est pas nécessaire.

Avec --follow, la commande continue de tourner, envoie les requêtes au fur et à mesure et continue quand le journal est renouvelé, en finissant l’ancien fichier avant de passer au nouveau. Un service systemd ou un gestionnaire de processus la maintient en marche. Ajoutez --state ./agents.json pour qu’un redémarrage reprenne là où elle s’est arrêtée. Sans --follow, elle lit le journal une fois et s’arrête, et avec --state, l’exécution suivante commence là où la précédente a fini, ce qui convient à cron. Une seule exécution à la fois peut utiliser un fichier d’état. Elle pose un verrou à côté du fichier (agents.json.lock), donc une deuxième exécution, comme une tâche cron qui démarre alors que la précédente envoie encore, s’arrête avec un message et n’envoie rien en double. Un verrou laissé par une exécution qui a planté est repris.

Seules les requêtes de pages réussies des agents IA connus quittent la machine, chacune avec l’adresse de la page, le user agent de l’agent et le moment où elle a été servie. Les adresses des visiteurs et tout le reste du journal restent où ils sont.