Déployer sur votre propre serveur (agent Menestrel)

L’agent Menestrel est un petit daemon open source (MIT) qui tourne sur votre propre serveur. À chaque publication, Menestrel lui envoie un ping signé ; l’agent tire votre dépôt Git, reconstruit le site statique, vérifie le résultat et le bascule en ligne de façon atomique. Votre hébergement ne quitte jamais votre machine, et la timeline Menestrel affiche quand même « En ligne à 14 h 32 ».

Les prérequis, sans enjolivure : Node 22 ou plus récent, git, environ 2 Go de RAM libres pour un build Astro avec traitement d’images local (sinon, préférez le pipeline d’images Menestrel), un accès sortant vers votre hébergeur Git et l’API Menestrel, et un chemin HTTPS vers l’agent (un reverse proxy devant lui).

1. Créez la cible dans Menestrel

   Dans les réglages du site, ouvrez Déploiement et connectez un hébergeur de type « Votre serveur (agent Menestrel) ». Saisissez l’URL publique de l’agent, par exemple https://vps.exemple.fr/menestrel-agent. Menestrel génère le secret partagé (agt_...) et l’affiche une seule fois : copiez-le maintenant.

2. Installez l’agent sur le serveur

   npm install -g @menestrel/agent
   sudo menestrel-agent init

   init vérifie les prérequis, crée l’utilisateur système menestrel-agent, demande le dépôt, la branche, la commande de build et le secret de l’étape 1, puis écrit /etc/menestrel-agent/<site>.toml (mode 600) et l’unité systemd. Il imprime aussi les snippets Caddy et nginx pour le reverse proxy.

   Astuce

   Installez en global plutôt que par npx : un daemon ne doit pas dépendre du réseau npm au démarrage.

3. Démarrez et testez

   sudo systemctl enable --now menestrel-agent-<site>

   Côté Menestrel, utilisez le bouton « Tester (construction à blanc) » de la cible : l’agent fait un build complet sans toucher au site en ligne et remonte la durée de référence.

Au quotidien

• La file coalesce : des publications qui arrivent pendant un build se replient en exactement un rebuild final.
• Un build cassé ne part jamais en ligne : le résultat est vérifié avant la bascule atomique, et les releases précédentes (5 par défaut) restent sur le disque.
• Rollback local, pour le cas où même le rebuild est cassé : menestrel-agent rollback re-pointe la release en ligne ; menestrel-agent status l’affiche. Le rollback normal reste « republier une version précédente » depuis l’admin.
• Après 3 builds en échec, la cible se met en pause et les admins reçoivent un email ; réactivez-la depuis les réglages du site.

La sécurité en un paragraphe : l’agent expose exactement deux endpoints (POST /deploy, signé, et un GET /health volontairement pauvre), ne reçoit jamais ni code ni commande, ne tire que le dépôt écrit dans sa configuration locale, vérifie chaque requête par signature HMAC avec une fenêtre anti-rejeu de 5 minutes, et ne rappelle que l’adresse d’API épinglée dans cette même configuration.