Documentation Klystrr

Qu'est-ce que Klystrr ?

Klystrr est une plateforme de déploiement conçue pour les développeurs qui souhaitent un contrôle total sur leur infrastructure. Elle fait le lien entre vos dépôts Git et vos propres serveurs VPS — vous permettant de déployer, gérer et surveiller des applications via un tableau de bord épuré, sans écrire de scripts shell ni configurer des serveurs manuellement.

Klystrr gère la couche opérationnelle d'un déploiement : connexion SSH, clonage du dépôt, installation des dépendances, gestion des processus via PM2, configuration du proxy inverse via Nginx ou Apache, et provisionnement automatique des certificats SSL. Vous vous concentrez sur votre code ; Klystrr gère ce qui se passe après votre push.

Pour qui est-il conçu ?

• Les développeurs indépendants qui hébergent une ou plusieurs applications sur un VPS et souhaitent un workflow de déploiement plus rapide et fiable
• Les petites équipes techniques ayant besoin d'une couche de déploiement légère sans la complexité d'une plateforme CI/CD complète
• Les développeurs quittant l'hébergement managé qui souhaitent réduire leurs coûts en utilisant leurs propres serveurs sans perdre le confort de déploiement

Klystrr suppose une familiarité technique avec les serveurs Linux, SSH et Git. Ce n'est pas un outil no-code.

Quel problème résout-il ?

Déployer une application sur un VPS implique généralement de :

• Se connecter manuellement en SSH au serveur
• Récupérer le dernier code
• Installer les dépendances
• Lancer un build
• Redémarrer le processus
• Vérifier que Nginx sert le trafic
• Renouveler les certificats SSL

Faire cela répétitivement — sur plusieurs projets ou serveurs — est source d'erreurs et chronophage. Klystrr automatise chaque étape et vous offre un historique complet de chaque déploiement.

Informations VPS requises

• Hôte — l'adresse IP publique ou le nom d'hôte de votre VPS
• Port SSH — généralement 22, sauf si vous avez configuré un port personnalisé
• Utilisateur SSH — un utilisateur Linux avec des permissions suffisantes
• Authentification — mot de passe ou clé privée SSH (clé recommandée)

Prérequis d'accès SSH

L'utilisateur SSH fourni à Klystrr doit pouvoir :

• Lire et écrire dans le répertoire de déploiement (par défaut : /var/www/)
• Exécuter git, node, npm / pnpm / yarn
• Exécuter les commandes pm2
• Recharger Nginx ou Apache (généralement via sudo sans invite de mot de passe)

Si vous n'utilisez pas root, configurez sudo sans mot de passe pour la commande de rechargement :

# Add to /etc/sudoers.d/klystrr-deploy
your_user ALL=(ALL) NOPASSWD: /usr/sbin/nginx
# or for Apache:
your_user ALL=(ALL) NOPASSWD: /usr/sbin/apachectl

Liste de contrôle de pré-installation :

git --version
node -v
npm -v
pm2 -v
nginx -v   # or apache2 -v
certbot --version

Serveurs web supportés

Nginx est l'option par défaut et recommandée. Klystrr génère automatiquement un bloc serveur qui proxifie le trafic depuis votre domaine par défaut vers le port local de votre application.

Apache (apache2) est également supporté. Klystrr génère une configuration VirtualHost Apache et recharge le service après chaque déploiement. Assurez-vous que mod_proxy et mod_proxy_http sont activés :

sudo a2enmod proxy proxy_http

Permissions requises

Recommandations de sécurité

• Utilisez un utilisateur de déploiement dédié plutôt que root. Un utilisateur nommé deploy avec des permissions limitées réduit l'impact d'une mauvaise configuration.
• Utilisez l'authentification par clé SSH plutôt que par mot de passe. Générez une paire de clés dédiée pour Klystrr.
• Désactivez l'authentification par mot de passe sur SSH une fois votre clé en place.
• Maintenez votre serveur à jour : apt update && apt upgrade régulièrement.
• Utilisez un pare-feu : n'ouvrez que les ports requis (80, 443, 22).
• Faites pivoter les identifiants périodiquement et mettez-les à jour dans les paramètres du serveur Klystrr.

# /etc/ssh/sshd_config
PasswordAuthentication no

Sélection du dépôt

Sélectionnez un dépôt dans la liste des dépôts accessibles via votre compte GitHub ou GitLab connecté. Les dépôts publics et privés sont supportés.

Si un dépôt n'apparaît pas, vérifiez que votre connexion OAuth dispose du périmètre d'accès correct, ou que le dépôt appartient à une organisation que vous avez autorisée.

Sélection de la branche

Sélectionnez la branche depuis laquelle Klystrr doit déployer (ex. main, production, release). Seule la branche sélectionnée est utilisée. Si vous activez le déploiement automatique, un webhook est enregistré sur cette branche uniquement.

Commande d'installation

La commande utilisée pour installer les dépendances de votre projet, exécutée après le clonage ou la mise à jour du dépôt.

# Examples
npm install
pnpm install
yarn install
pip install -r requirements.txt

Laissez vide si votre projet n'a pas de dépendances à installer.

Commande de build

La commande utilisée pour compiler ou bundler votre application, exécutée après l'étape d'installation.

# Examples
npm run build
pnpm build
tsc

Laissez vide si votre application ne nécessite pas d'étape de build.

Commande de démarrage

La commande utilisée pour démarrer votre application. Klystrr l'encapsule avec PM2 — n'incluez pas pm2 start vous-même.

# Examples
node dist/main.js
npm run start:prod
python app.py
./bin/server

PM2 gère le processus comme un service d'arrière-plan persistant. Si le serveur redémarre, PM2 tentera de redémarrer votre application automatiquement (si pm2 save et pm2 startup sont configurés).

Variables d'environnement

Allez dans l'onglet Environnement de votre projet pour gérer les variables d'environnement.

• Les variables sont chiffrées au repos et ne sont jamais renvoyées via l'API après soumission initiale
• Les valeurs sont masquées dans les journaux de déploiement
• Les modifications prennent effet lors du prochain déploiement — elles ne sont pas rechargées à chaud
• Utilisez l'éditeur en masse (format CLÉ=VALEUR) ou l'interface de champ individuel

NODE_ENV=production
PORT=3000
DATABASE_URL=postgres://user:pass@host:5432/db
JWT_SECRET=your-secret-here

Déploiement manuel

Allez sur la page de votre projet et cliquez sur Déployer. Klystrr mettra immédiatement en file d'attente et démarrera le déploiement avec la configuration actuelle du projet et le dernier commit sur la branche configurée.

Redéploiement

Chaque déploiement exécute la séquence complète depuis le début : récupération du code → installation → build → redémarrage PM2 → mise à jour du proxy → vérification SSL. Il n'y a pas de déploiement partiel ou incrémental.

Statut de déploiement

Un déploiement échoué ne revient pas automatiquement en arrière. Selon où l'échec s'est produit, votre version précédente est peut-être encore en cours d'exécution via PM2.

Journaux de déploiement

Les journaux en temps réel sont accessibles depuis la vue de détail du déploiement et incluent les commandes exactes exécutées par Klystrr, la sortie stdout/stderr, les libellés de phase, les horodatages et le statut de sortie. Les valeurs sensibles des variables d'environnement sont masquées. Les journaux sont conservés 90 jours.

Historique des déploiements

Tous les déploiements passés sont listés dans l'onglet Historique de votre projet. Chaque entrée affiche le type de déclenchement, le déclencheur, l'horodatage, la durée, le statut final et un lien vers le journal complet.

Rollback

Klystrr ne propose pas encore de rollback en un clic. Si un déploiement échoue ou introduit une régression, vous pouvez récupérer manuellement :

# SSH into your server
ssh user@your-server

# Go to the deployment directory
cd /var/www/your-project-name

# Reset to a specific previous commit
git log --oneline         # find the commit you want
git reset --hard <sha>

# Restart the application
pm2 restart your-project-name

Le rollback automatique avec récupération par snapshot est prévu pour une prochaine version.

Domaines Klystrr par défaut

Chaque projet reçoit automatiquement un sous-domaine par défaut :

https://<project-name>.klystrr.app

Le domaine par défaut est provisionné lors de votre premier déploiement réussi. Aucune configuration DNS n'est requise de votre côté. Les noms de domaine sont dérivés du nom de votre projet et doivent être en minuscules, alphanumériques, et peuvent inclure des tirets.

Comportement du proxy inverse

Klystrr configure un proxy inverse sur votre serveur pour router le trafic depuis votre domaine par défaut vers le port local de votre application. Votre application n'a pas besoin de gérer TLS ou le port 443 directement.

Exemple Nginx :

server {
    server_name my-api.klystrr.app;

    location / {
        proxy_pass http://127.0.0.1:3000;
        proxy_http_version 1.1;
        proxy_set_header Upgrade $http_upgrade;
        proxy_set_header Connection 'upgrade';
        proxy_set_header Host $host;
        proxy_cache_bypass $http_upgrade;
    }
}

Exemple Apache :

<VirtualHost *:80>
    ServerName my-api.klystrr.app

    ProxyPreserveHost On
    ProxyPass / http://127.0.0.1:3000/
    ProxyPassReverse / http://127.0.0.1:3000/
</VirtualHost>

Génération SSL

Klystrr provisionne les certificats SSL automatiquement via Let's Encrypt et Certbot lors du déploiement. Tout le trafic HTTP est redirigé définitivement vers HTTPS. Les certificats sont valides 90 jours et auto-renouvelés par le job planifié Certbot sur votre serveur.

Vérifiez que le timer Certbot est actif :

sudo systemctl status certbot.timer

Domaines personnalisés (prévu)

La prise en charge des domaines personnalisés (ex. api.votredomaine.com) est prévue pour une prochaine version. Lorsqu'elle sera disponible, elle permettra de pointer votre propre domaine vers un projet Klystrr via un enregistrement CNAME et de bénéficier d'un provisionnement SSL automatique. Cette section sera mise à jour lorsque la fonctionnalité sera disponible.

Connexion GitHub

Allez dans Paramètres → Intégrations → GitHub et cliquez sur Connecter GitHub. Après autorisation OAuth, Klystrr peut lister et accéder aux dépôts que vous possédez ou auxquels vous avez accès.

Révoquer à tout moment : GitHub → Paramètres → Applications → Authorized OAuth Apps → Klystrr → Révoquer.

Connexion GitLab

Allez dans Paramètres → Intégrations → GitLab et cliquez sur Connecter GitLab. Les comptes hébergés sur gitlab.com et les instances GitLab auto-hébergées sont supportés (contactez le support pour la configuration auto-hébergée).

Révoquer à tout moment : GitLab → Paramètres → Applications → trouver Klystrr → Révoquer.

Permissions OAuth expliquées

Klystrr demande les permissions minimales nécessaires. Il ne demande pas d'accès administrateur, d'accès en écriture à votre code, d'accès à vos issues, PRs, secrets, ni à aucune donnée au-delà de ce qui est nécessaire pour cloner les dépôts et gérer les webhooks.

Les tokens OAuth sont chiffrés au repos et jamais exposés dans l'interface ou les réponses API après l'autorisation initiale.