test/SETUP_PM2.md

Configuration PM2 pour Runlock.re

Ce guide explique comment configurer PM2 pour que votre application se relance automatiquement après un crash ou un redémarrage du serveur.

📋 Prérequis

• Node.js installé sur le serveur
• Application qui fonctionne avec npm run dev
• Accès SSH au serveur

---

🚀 Étape 1 : Installer PM2 globalement

sudo npm install -g pm2

Vérifier l'installation :

pm2 --version

---

🔨 Étape 2 : Builder l'application pour la production

D'abord, arrêtez votre application en cours (Ctrl+C si elle tourne avec npm run dev).

Puis build l'application :

npm run build

---

🎯 Étape 3 : Configurer PM2 avec ecosystem.config.js

Le fichier ecosystem.config.js est déjà créé dans votre projet.

Important : Si vous êtes dans un environnement de production, assurez-vous que :

1. Le fichier .env.local existe avec vos variables d'environnement
2. Le port 3000 est disponible (ou changez-le dans ecosystem.config.js)

---

▶️ Étape 4 : Démarrer l'application avec PM2

pm2 start ecosystem.config.js

Vous devriez voir quelque chose comme :

[PM2] Starting ecosystem.config.js
[PM2] Process launched
┌─────────┬────────┬─────────┬─────────┬─────────┐
│ App name│ id     │ mode    │ pid     │ status  │
├─────────┼────────┼─────────┼─────────┼─────────┤
│ runlock │ 0      │ cluster │ 12345   │ online  │
└─────────┴────────┴─────────┴─────────┴─────────┘

---

🔄 Étape 5 : Sauvegarder la configuration PM2

Pour que PM2 redémarre l'application au boot du serveur :

pm2 save
pm2 startup

La commande pm2 startup affichera une commande à exécuter avec sudo. Copiez et exécutez cette commande.

Exemple :

sudo env PATH=$PATH:/usr/bin /usr/lib/node_modules/pm2/bin/pm2 startup systemd -u votre-utilisateur --hp /home/votre-utilisateur

---

✅ Étape 6 : Vérifier que tout fonctionne

Vérifier le statut

pm2 status

Voir les logs

pm2 logs runlock

Voir les logs en temps réel

pm2 logs runlock --lines 50

---

🛠️ Commandes PM2 utiles

# Voir le statut
pm2 status

# Voir les logs
pm2 logs runlock

# Voir les 50 dernières lignes
pm2 logs runlock --lines 50

# Redémarrer l'application
pm2 restart runlock

# Arrêter l'application
pm2 stop runlock

# Supprimer l'application de PM2
pm2 delete runlock

# Monitoring en temps réel
pm2 monit

# Redémarrer toutes les applications
pm2 restart all

# Voir les informations détaillées
pm2 show runlock

# Vider les logs
pm2 flush

# Recharger sans downtime (recommandé pour les mises à jour)
pm2 reload runlock

---

🔄 Mise à jour de l'application

Quand vous mettez à jour votre application :

# 1. Aller dans le dossier du projet
cd /chemin/vers/runlock-v2

# 2. Récupérer les dernières modifications (si Git)
git pull

# 3. Installer les nouvelles dépendances
npm install

# 4. Rebuild l'application
npm run build

# 5. Recharger PM2 (reload = zéro downtime)
pm2 reload runlock

# Ou redémarrer complètement
pm2 restart runlock

---

🔍 Dépannage

L'application ne démarre pas

1. Vérifiez les logs :

pm2 logs runlock --lines 100

2. Vérifiez que le port 3000 est libre :

sudo netstat -tulpn | grep 3000

3. Vérifiez que .env.local existe :

ls -la .env.local

L'application ne redémarre pas au boot

1. Vérifiez que pm2 startup a été exécuté :

pm2 startup

2. Vérifiez que PM2 est sauvegardé :

pm2 save

L'application crash en boucle

1. Vérifiez les logs pour voir l'erreur :

pm2 logs runlock --err

2. Vérifiez la mémoire disponible :

free -h

3. Réduisez max_memory_restart dans ecosystem.config.js si nécessaire

---

🔐 Sécurité

Changer le port (si nécessaire)

Si le port 3000 est déjà utilisé, modifiez ecosystem.config.js :

env: {
  NODE_ENV: 'production',
  PORT: 3001  // Changez le port ici
}

Puis redémarrez :

pm2 restart runlock

Limiter les logs

Pour éviter que les logs prennent trop de place :

pm2 install pm2-logrotate
pm2 set pm2-logrotate:max_size 10M
pm2 set pm2-logrotate:retain 7

---

📊 Monitoring

Dashboard PM2 Plus (optionnel)

PM2 offre un dashboard en ligne gratuit :

pm2 link [secret_key] [public_key]

Les clés sont disponibles sur pm2.io

Monitoring local

pm2 monit

Cette commande affiche :

• Utilisation CPU
• Utilisation mémoire
• Logs en temps réel

---

✅ Test final

Pour tester que tout fonctionne :

1. Test de redémarrage manuel :

pm2 restart runlock

2. Test de crash :

# Tuer le processus manuellement (ne faites pas ça en production !)
pm2 delete runlock
pm2 start ecosystem.config.js
# PM2 devrait le relancer automatiquement

3. Test au boot :

# Redémarrer le serveur
sudo reboot
# Après le redémarrage, vérifiez
pm2 status
# L'application devrait être "online"

---

📝 Résumé rapide

Pour démarrer rapidement :

# 1. Installer PM2
sudo npm install -g pm2

# 2. Builder l'app
npm run build

# 3. Démarrer avec PM2
pm2 start ecosystem.config.js

# 4. Sauvegarder pour le boot
pm2 save
pm2 startup
# (Suivez les instructions affichées)

# 5. Vérifier
pm2 status
pm2 logs runlock

---

Dernière mise à jour : 2025