Skip to content

Maintenance et bonnes pratiques

English version
← Retour au sommaire

Sauvegardes

⚠️ Correction importante : Les anciens guides mentionnaient les "sauvegardes automatiques Supabase". La base de données est maintenant sur PostgreSQL auto-hébergé — les sauvegardes doivent être gérées explicitement.

Base de données PostgreSQL

Sauvegarde automatique : un service Docker backup (ou un cron sur le serveur) peut être configuré pour exécuter pg_dump régulièrement.

Sauvegarde manuelle :

# Sur le serveur
pg_dump -h postgres -U postgres -d racines -F c -f /backups/racines_$(date +%Y%m%d).dump

Restauration :

pg_restore -h postgres -U postgres -d racines /backups/racines_20260515.dump

Recommandations : - Sauvegarde quotidienne minimum - Rétention 30 jours minimum - Stockage des backups hors du même serveur (S3, MinIO distant, etc.) - Test de restauration mensuel

Fichiers audio MinIO

Les fichiers audio sont stockés dans le bucket audios avec le versioning activé (chaque ré-enregistrement crée une nouvelle version, l'ancienne est conservée).

Sauvegarde MinIO :

# Via mc (MinIO Client)
mc mirror minio/audios /backup/audios/

# Ou via script npm fourni
npm run audio:download-originals

Monitoring

Health check de l'application

L'endpoint de santé est disponible en permanence :

GET /api/health/live

Réponse attendue (statut HTTP 200) :

{ "status": "ok", "timestamp": "2026-05-31T12:00:00Z" }

Ce endpoint est utilisé par Docker (healthcheck toutes les 30s) et peut être surveillé par un outil externe (UptimeRobot, Grafana, etc.).

Logs de l'application

Accéder aux logs via Docker :

# Logs en temps réel
docker logs -f racines-app

# Dernières 100 lignes
docker logs --tail=100 racines-app

# Logs depuis 1 heure
docker logs --since=1h racines-app

Patterns à surveiller : - Erreurs 500 dans les routes /api/audio/upload - Messages AUDIO_CDN_URL is empty (variable d'environnement manquante) - Erreurs de connexion PostgreSQL (ECONNREFUSED, too many clients) - Violations CSP (Refused to connect dans les logs client)

Espace disque

Surveillez l'espace disque du serveur, notamment : - /var/lib/docker/volumes/ : données PostgreSQL et MinIO - /backups/ : sauvegardes pg_dump

df -h
du -sh /var/lib/docker/volumes/*

Mise à jour de l'application

Via le pipeline CI/CD (recommandé)

Tout push sur la branche develop (ou main/production) déclenche le pipeline GitLab qui : 1. Lint + tests 2. Build de l'image Docker 3. Push vers GitLab Registry 4. Déploiement via Ansible (SSH + docker pull + docker-compose up -d)

Via SSH manuelle (urgence)

# Sur le serveur
cd /opt/racines
docker-compose pull app
docker-compose up -d app
docker-compose ps  # Vérifiez que tous les services sont "Up"

Après une mise à jour

Vérifiez : 1. GET /api/health/live → { "status": "ok" } 2. La page d'accueil se charge correctement 3. Un audio se lit depuis le CDN 4. La page admin est accessible 5. L'interface locuteur est accessible

Optimisation des performances

Pool de connexions PostgreSQL

Le pool est configuré à 20 connexions maximum (fichier src/lib/postgres.ts). En cas de pic de charge, les connexions sont mises en file d'attente (timeout 10s). Si vous voyez des erreurs connection timeout, augmentez le pool ou vérifiez les requêtes lentes.

Requêtes lentes :

-- Requêtes longues en cours
SELECT pid, now() - pg_stat_activity.query_start AS duration, query
FROM pg_stat_activity
WHERE (now() - pg_stat_activity.query_start) > interval '5 seconds';

Cache audio CDN

Assurez-vous que AUDIO_CDN_URL est défini et correct. Un CDN bien configuré (MinIO accessible publiquement ou via un CDN tiers) est crucial pour les performances audio.

Résolution des problèmes courants

Les audios ne se chargent pas

Vérifications : 1. La variable AUDIO_CDN_URL est-elle définie ? → docker inspect racines-app | grep AUDIO_CDN_URL 2. L'URL CDN est-elle accessible depuis l'extérieur ? → curl -I [AUDIO_CDN_URL]/test.mp3 3. Les CORS MinIO sont-ils configurés ? → Le header Access-Control-Allow-Origin est-il présent ? 4. La CSP bloque-t-elle le domaine CDN ? → Vérifiez AUDIO_CDN_DOMAIN dans les env vars

La page admin est inaccessible

  1. Vérifiez que le container app tourne : docker-compose ps
  2. Vérifiez les logs : docker logs racines-app --tail=50
  3. Testez le health check : curl http://localhost:3000/api/health/live
  4. Vérifiez Traefik (reverse proxy) : docker logs traefik --tail=50

L'import Excel échoue en production

  1. Vérifiez la taille du fichier (> 50MB ?)
  2. Vérifiez l'encodage UTF-8 du fichier
  3. Vérifiez les logs de l'app pour le détail de l'erreur

Le Service Worker n'est pas mis à jour chez les joueurs

Après un déploiement, les joueurs peuvent garder l'ancienne version en cache. Solutions : - L'application détecte automatiquement la mise à jour et affiche une bannière "Mise à jour disponible" - Le joueur doit recharger manuellement la page ou cliquer sur la bannière - En cas de problème persistant : le joueur doit vider son cache navigateur

Sécurité

Bonnes pratiques

  1. Changez régulièrement les mots de passe admin (via npm run create-admin ou SQL direct)
  2. Limitez le nombre d'administrateurs — chaque admin doit avoir ses propres identifiants
  3. Ne committez jamais les fichiers .env dans Git (déjà dans .gitignore)
  4. Régénérez JWT_SECRET si vous suspectez une compromission — toutes les sessions actives sont invalidées

Variables d'environnement sensibles

Toutes les variables sensibles sont stockées dans les secrets GitLab CI/CD et dans le fichier .app_env sur le serveur (hors Git).

Variables critiques à ne jamais exposer : - JWT_SECRET - PG_PASSWORD - MINIO_SECRET_KEY - MINIO_ACCESS_KEY

Étapes suivantes