Aller au contenu

Alert-Parent — Erreurs courantes

Backend ne démarre pas

Symptôme : docker compose ps montre le backend en "Restarting"

Causes possibles :

  1. .env manquant ou incomplet → vérifier que .env existe et contient toutes les variables
  2. MONGO_URI invalide → vérifier la chaîne de connexion Atlas
  3. Port déjà utilisé → lsof -i :5011

Diagnostic :

cd /root/projects/alert-parent/alert-parent-backend
docker compose logs backend --tail 50

Port already allocated

Symptôme : docker compose up échoue avec port is already allocated

Cause : Un ancien conteneur utilise encore le port.

Solution :

# Identifier le conteneur qui utilise le port
docker ps --format "table {{.Names}}\t{{.Ports}}" | grep 5011

# Arrêter l'ancien conteneur
docker stop NOM_CONTENEUR
docker rm NOM_CONTENEUR

# Relancer
docker compose up -d

Permission denied sur .env

Symptôme : Le pipeline échoue avec Permission denied lors de l'écriture du .env

Cause : L'utilisateur SSH n'a pas les droits sur le répertoire du projet.

Solution :

chown -R UTILISATEUR:UTILISATEUR /root/projects/alert-parent/alert-parent-backend

GHCR denied (pull image échoue)

Symptôme : docker compose pull échoue avec denied ou unauthorized

Causes :

  1. Le VPS n'est pas authentifié auprès de GHCR
  2. Le token a expiré

Solution :

# Se connecter à GHCR
echo $GITHUB_TOKEN | docker login ghcr.io -u USERNAME --password-stdin

# Ou vérifier les permissions du repo
# Settings > Actions > General > Workflow permissions > Read and write

git pull échoue sur le VPS

Symptôme : Le pipeline échoue à l'étape git pull avec Permission denied (publickey)

Cause : Le VPS n'a pas de clé SSH GitHub configurée pour les repos privés.

Solution : Ne pas utiliser git pull. Le pipeline doit utiliser SCP pour copier le docker-compose.yml. Voir le guide CI/CD.

MongoDB ECONNREFUSED

Symptôme : Le health check retourne 503 avec mongodb.status: "error"

Causes possibles :

  1. Le fichier .env est vide : le MONGO_URI n'est pas défini 
    cat /root/projects/alert-parent/alert-parent-backend/.env | wc -l
# Si 0 → le DOTENV_FILE secret est vide ou manquant
  2. L'IP du VPS n'est pas dans la whitelist Atlas : aller sur cloud.mongodb.com > Network Access > ajouter l'IP du VPS
  3. Le cluster Atlas est en pause : vérifier le statut du cluster dans le dashboard Atlas

Health check échoue (503)

Symptôme : /health retourne {"status": "degraded"}

Cause : MongoDB n'est pas accessible

Actions :

  1. Vérifier le statut MongoDB Atlas dans le dashboard Atlas
  2. Vérifier que l'IP du VPS est dans la whitelist Atlas
  3. Tester la connexion : 
    docker compose exec backend node -e "require('mongoose').connect(process.env.MONGO_URI)"

Emails ne s'envoient pas

Symptôme : MailSended reste à isSent: "no"

Causes :

  1. RESEND_TOKEN invalide → vérifier dans le dashboard Resend
  2. Quota Resend dépassé → vérifier les limites
  3. Erreur dans la boucle mail → chercher "Mail loop error" dans les logs

Diagnostic :

docker compose logs backend | grep -i "mail"

Container "unhealthy"

Symptôme : docker compose ps montre "(unhealthy)"

Action : Le healthcheck /health échoue. Vérifier les logs et la connexion MongoDB.

docker compose logs backend --tail 50
curl -s http://127.0.0.1:5011/health | python3 -m json.tool

Pipeline CI/CD échoue

Job Build échoue

  • "pnpm-lock.yaml not found" : le fichier doit être commité dans le repo
  • "unauthorized" : vérifier les permissions GHCR du repo (Settings > Actions > General > Workflow permissions > Read and write)

Job Deploy échoue

  • "Connection refused" : vérifier SERVER_HOST et que le VPS est accessible
  • "Permission denied" : vérifier SERVER_SSH_KEY (clé privée complète, incluant les lignes BEGIN et END)
  • "docker: command not found" : Docker n'est pas installé sur le VPS ou l'utilisateur n'est pas dans le groupe docker (usermod -aG docker UTILISATEUR)