NeahStable/docs/RUNBOOK.md

Runbook de Production - Neah

Ce document contient toutes les procédures opérationnelles pour gérer Neah en production.

Table des matières

1. Déploiement
2. Exploitation quotidienne
3. Incidents
4. Rollback
5. Maintenance
6. Contacts

---

Déploiement

Déploiement standard (Vercel)

Prérequis

• Toutes les migrations Prisma sont testées en staging
• Les variables d'environnement sont à jour dans Vercel
• Les tests passent localement: npm run build

Étapes

1. Vérifier l'état actuel

# Vérifier les migrations en attente
npx prisma migrate status

# Vérifier la configuration
./scripts/verify-vercel-config.sh

2. Appliquer les migrations Prisma

# Se connecter au serveur PostgreSQL (via tunnel SSH si nécessaire)
export DATABASE_URL="postgresql://user:password@host:5432/calendar_db"

# Appliquer les migrations
./scripts/migrate-prod.sh

# OU manuellement
npx prisma migrate deploy

3. Déployer sur Vercel

Le déploiement se fait automatiquement via Git:

# Pousser les changements vers la branche main
git push origin main

# Vercel déploiera automatiquement
# Surveiller le déploiement dans Vercel Dashboard

OU manuellement via CLI:

vercel --prod

4. Vérifier le déploiement

• Vérifier les logs Vercel pour les erreurs
• Tester l'endpoint de santé: GET https://votre-domaine.vercel.app/api/health
• Tester l'authentification
• Vérifier les fonctionnalités critiques

Déploiement avec migrations critiques

Si les migrations modifient des données existantes:

1. Sauvegarder la base de données

# Sauvegarde complète
docker exec neah-postgres-prod pg_dump -U neah_prod_user calendar_db > backup_$(date +%Y%m%d_%H%M%S).sql

# Sauvegarde compressée
docker exec neah-postgres-prod pg_dump -U neah_prod_user calendar_db | gzip > backup_$(date +%Y%m%d_%H%M%S).sql.gz

2. Tester les migrations en staging

3. Appliquer en production (voir procédure standard)

4. Vérifier l'intégrité des données

-- Exemples de vérifications
SELECT COUNT(*) FROM "User";
SELECT COUNT(*) FROM "Mission";
SELECT COUNT(*) FROM "Event";

---

Exploitation quotidienne

Vérifications quotidiennes

1. Santé de l'application

# Vérifier l'endpoint de santé
curl https://votre-domaine.vercel.app/api/health

# Vérifier les logs Vercel récents
vercel logs --follow

2. Santé de PostgreSQL

# Se connecter au serveur
ssh user@your-server

# Vérifier l'état du conteneur
docker ps | grep neah-postgres-prod

# Vérifier les connexions actives
docker exec neah-postgres-prod psql -U neah_prod_user -d calendar_db -c "
SELECT count(*) as active_connections 
FROM pg_stat_activity 
WHERE datname = 'calendar_db';
"

# Vérifier l'espace disque
docker exec neah-postgres-prod df -h

3. Santé de Redis

# Vérifier l'état du conteneur
docker ps | grep neah-redis-prod

# Vérifier la mémoire utilisée
docker exec neah-redis-prod redis-cli INFO memory

# Vérifier les clés
docker exec neah-redis-prod redis-cli DBSIZE

4. Métriques Vercel

• Consulter Vercel Dashboard → Analytics
• Vérifier:
  • Taux d'erreur (< 1%)
  • Temps de réponse (< 500ms)
  • Trafic normal

Tâches hebdomadaires

Sauvegarde de la base de données

#!/bin/bash
# scripts/backup-db.sh

BACKUP_DIR="/opt/neah/backups"
DATE=$(date +%Y%m%d_%H%M%S)
BACKUP_FILE="$BACKUP_DIR/backup_$DATE.sql.gz"

mkdir -p "$BACKUP_DIR"

docker exec neah-postgres-prod pg_dump -U neah_prod_user calendar_db | gzip > "$BACKUP_FILE"

# Garder uniquement les 7 derniers backups
ls -t $BACKUP_DIR/backup_*.sql.gz | tail -n +8 | xargs rm -f

echo "Backup créé: $BACKUP_FILE"

Automatisation avec cron:

# Ajouter à crontab (crontab -e)
0 2 * * * /opt/neah/scripts/backup-db.sh >> /var/log/neah-backup.log 2>&1

Nettoyage des logs

# Nettoyer les anciens logs Docker (garder 7 jours)
docker system prune -f --filter "until=168h"

---

Incidents

Procédure générale

1. Identifier le problème

   • Consulter les logs Vercel
   • Vérifier l'endpoint /api/health
   • Vérifier les logs PostgreSQL/Redis

2. Évaluer l'impact

   • Nombre d'utilisateurs affectés
   • Fonctionnalités impactées
   • Criticité (P1, P2, P3)

3. Contenir le problème

   • Rollback si nécessaire (voir section Rollback)
   • Désactiver les fonctionnalités problématiques
   • Communiquer avec les utilisateurs

4. Résoudre

   • Corriger le problème
   • Tester en staging
   • Déployer en production

5. Post-mortem

   • Documenter l'incident
   • Identifier les causes racines
   • Mettre en place des mesures préventives

Scénarios courants

Scénario 1: Application inaccessible (503)

Symptômes:

• Erreur 503 sur toutes les pages
• Health check échoue

Actions:

1. Vérifier Vercel Dashboard → Deployments
2. Vérifier les logs Vercel
3. Vérifier la connexion à PostgreSQL:

# Tester la connexion
psql $DATABASE_URL -c "SELECT 1;"

4. Vérifier les variables d'environnement dans Vercel
5. Si problème persistant, rollback vers version précédente

Scénario 2: Erreurs de base de données

Symptômes:

• Erreurs "Connection refused" ou "Connection timeout"
• Health check indique database: error

Actions:

1. Vérifier l'état du conteneur PostgreSQL:

docker ps | grep neah-postgres-prod
docker logs neah-postgres-prod --tail 50

2. Vérifier les ressources:

docker stats neah-postgres-prod

3. Redémarrer si nécessaire:

docker restart neah-postgres-prod

4. Vérifier la connexion après redémarrage

Scénario 3: Performance dégradée

Symptômes:

• Temps de réponse élevés
• Timeouts fréquents

Actions:

1. Identifier les requêtes lentes:

-- Requêtes les plus lentes
SELECT 
  query,
  calls,
  mean_exec_time,
  max_exec_time
FROM pg_stat_statements
ORDER BY mean_exec_time DESC
LIMIT 10;

2. Vérifier les index manquants:

-- Tables sans index
SELECT 
  schemaname,
  tablename,
  attname,
  n_distinct,
  correlation
FROM pg_stats
WHERE schemaname = 'public'
  AND n_distinct > 100
  AND correlation < 0.1;

3. Optimiser les requêtes ou ajouter des index

4. Vérifier l'utilisation de Redis (cache)

Scénario 4: Erreurs d'authentification Keycloak

Symptômes:

• Utilisateurs ne peuvent pas se connecter
• Erreurs "Invalid token" ou "Authentication failed"

Actions:

1. Vérifier la configuration Keycloak dans Vercel
2. Vérifier que Keycloak est accessible:

curl https://keycloak.example.com/realms/neah/.well-known/openid-configuration

3. Vérifier les tokens dans les logs
4. Contacter l'administrateur Keycloak si nécessaire

---

Rollback

Rollback Vercel

Méthode 1: Via Dashboard (Recommandé)

1. Aller dans Vercel Dashboard → Deployments
2. Trouver le déploiement précédent (stable)
3. Cliquer sur "..." → "Promote to Production"
4. Confirmer le rollback

Méthode 2: Via CLI

# Lister les déploiements
vercel ls

# Rollback vers un déploiement spécifique
vercel rollback [deployment-url]

Rollback de migration Prisma

ATTENTION: Les rollbacks de migration peuvent être destructifs. Toujours tester en staging d'abord.

Méthode 1: Migration de rollback

Si une migration de rollback existe:

export DATABASE_URL="postgresql://..."
npx prisma migrate resolve --rolled-back [migration-name]
npx prisma migrate deploy

Méthode 2: Restauration depuis sauvegarde

# Arrêter l'application si nécessaire
# Restaurer la sauvegarde
cat backup_20240112_120000.sql | docker exec -i neah-postgres-prod psql -U neah_prod_user calendar_db

# OU avec compression
gunzip < backup_20240112_120000.sql.gz | docker exec -i neah-postgres-prod psql -U neah_prod_user calendar_db

# Vérifier l'intégrité
docker exec neah-postgres-prod psql -U neah_prod_user -d calendar_db -c "SELECT COUNT(*) FROM \"User\";"

Procédure complète de rollback

1. Évaluer l'impact

   • Identifier les changements à annuler
   • Vérifier les dépendances

2. Sauvegarder l'état actuel

# Sauvegarde avant rollback
docker exec neah-postgres-prod pg_dump -U neah_prod_user calendar_db > backup_before_rollback_$(date +%Y%m%d_%H%M%S).sql

3. Rollback Vercel (voir ci-dessus)

4. Rollback base de données (si nécessaire)

5. Vérifier

# Tester l'endpoint de santé
curl https://votre-domaine.vercel.app/api/health

# Tester les fonctionnalités critiques

6. Communiquer

• Informer l'équipe du rollback
• Documenter la raison du rollback
• Planifier la correction du problème

---

Maintenance

Maintenance planifiée

Mise à jour des dépendances

# Vérifier les mises à jour
npm outdated

# Mettre à jour (une dépendance à la fois)
npm update [package-name]

# Tester en local
npm run build
npm run dev

# Tester en staging avant production

Mise à jour PostgreSQL

# Arrêter le conteneur
docker stop neah-postgres-prod

# Sauvegarder
docker exec neah-postgres-prod pg_dump -U neah_prod_user calendar_db > backup_before_upgrade.sql

# Mettre à jour l'image dans docker-compose.prod.yml
# postgres:15-alpine → postgres:16-alpine

# Redémarrer
docker-compose -f docker-compose.prod.yml up -d db

# Vérifier
docker exec neah-postgres-prod psql -U neah_prod_user -d calendar_db -c "SELECT version();"

Nettoyage de la base de données

-- Analyser les tables
ANALYZE;

-- VACUUM (nettoyage)
VACUUM ANALYZE;

-- Vérifier les tables orphelines
SELECT 
  schemaname,
  tablename,
  pg_size_pretty(pg_total_relation_size(schemaname||'.'||tablename)) AS size
FROM pg_tables
WHERE schemaname = 'public'
ORDER BY pg_total_relation_size(schemaname||'.'||tablename) DESC;

Maintenance d'urgence

Redémarrage des services

# Redémarrer PostgreSQL
docker restart neah-postgres-prod

# Redémarrer Redis
docker restart neah-redis-prod

# Redémarrer tous les services
docker-compose -f docker-compose.prod.yml restart

Libération d'espace disque

# Vérifier l'espace disque
df -h

# Nettoyer les images Docker non utilisées
docker image prune -a

# Nettoyer les volumes non utilisés
docker volume prune

# Nettoyer les anciens logs
journalctl --vacuum-time=7d

---

Contacts

Équipe Neah

• DevOps: [email]
• Développement: [email]
• Support: [email]

Services externes

• Vercel Support: https://vercel.com/support
• Keycloak Admin: [contact]
• PostgreSQL: [contact serveur]

Escalade

1. Niveau 1: Équipe Neah
2. Niveau 2: Administrateur système
3. Niveau 3: Direction technique

---

Annexes

Commandes utiles

# Vérifier les logs en temps réel
vercel logs --follow

# Vérifier l'état des migrations
npx prisma migrate status

# Tester la connexion PostgreSQL
psql $DATABASE_URL -c "SELECT version();"

# Statistiques PostgreSQL
docker exec neah-postgres-prod psql -U neah_prod_user -d calendar_db -c "
SELECT 
  datname,
  numbackends,
  xact_commit,
  xact_rollback,
  blks_read,
  blks_hit
FROM pg_stat_database
WHERE datname = 'calendar_db';
"

# Statistiques Redis
docker exec neah-redis-prod redis-cli INFO stats

Checklist de déploiement

• Migrations testées en staging
• Variables d'environnement à jour
• Build local réussi
• Sauvegarde de la base de données
• Migrations appliquées
• Déploiement Vercel réussi
• Health check OK
• Tests fonctionnels passés
• Logs vérifiés (pas d'erreurs)

Checklist de rollback

• Sauvegarde avant rollback créée
• Déploiement précédent identifié
• Rollback Vercel effectué
• Rollback base de données (si nécessaire)
• Health check OK
• Tests fonctionnels passés
• Équipe informée
• Problème documenté