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

```bash
sudo npm install -g pm2
```

Vérifier l'installation :
```bash
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 :

```bash
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

```bash
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 :

```bash
pm2 save
pm2 startup
```

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

Exemple :
```bash
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

```bash
pm2 status
```

### Voir les logs

```bash
pm2 logs runlock
```

### Voir les logs en temps réel

```bash
pm2 logs runlock --lines 50
```

---

## 🛠️ Commandes PM2 utiles

```bash
# 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 :

```bash
# 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 :
```bash
pm2 logs runlock --lines 100
```

2. Vérifiez que le port 3000 est libre :
```bash
sudo netstat -tulpn | grep 3000
```

3. Vérifiez que `.env.local` existe :
```bash
ls -la .env.local
```

### L'application ne redémarre pas au boot

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

2. Vérifiez que PM2 est sauvegardé :
```bash
pm2 save
```

### L'application crash en boucle

1. Vérifiez les logs pour voir l'erreur :
```bash
pm2 logs runlock --err
```

2. Vérifiez la mémoire disponible :
```bash
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` :

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

Puis redémarrez :
```bash
pm2 restart runlock
```

### Limiter les logs

Pour éviter que les logs prennent trop de place :

```bash
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 :

```bash
pm2 link [secret_key] [public_key]
```

Les clés sont disponibles sur [pm2.io](https://pm2.io)

### Monitoring local

```bash
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** :
```bash
pm2 restart runlock
```

2. **Test de crash** :
```bash
# 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** :
```bash
# 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 :

```bash
# 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