Dépannage

Ce guide aide à résoudre les problèmes courants rencontrés avec PCH-SIG.

Diagnostic rapide

Vérifier l'état des services

# État des conteneurs
docker ps -a

# Santé de l'application
curl http://localhost:8000/api/health

Script de diagnostic

# diagnostic.ps1
Write-Host "=== Diagnostic PCH-SIG ===" -ForegroundColor Cyan

# Docker
Write-Host "`n[Docker]"
docker-machine status default

# Conteneurs
Write-Host "`n[Conteneurs]"
docker-machine ssh default "docker ps --format 'table {{.Names}}\t{{.Status}}'"

# Ports
Write-Host "`n[Ports]"
netsh interface portproxy show all

# Tests
Write-Host "`n[Tests]"
try {
    Invoke-WebRequest -Uri "http://localhost:3000" -UseBasicParsing -TimeoutSec 5 | Out-Null
    Write-Host "Frontend: OK" -ForegroundColor Green
} catch {
    Write-Host "Frontend: ERREUR" -ForegroundColor Red
}

try {
    Invoke-WebRequest -Uri "http://localhost:8000/api" -UseBasicParsing -TimeoutSec 5 | Out-Null
    Write-Host "API: OK" -ForegroundColor Green
} catch {
    Write-Host "API: ERREUR" -ForegroundColor Red
}

---

Problèmes de connexion

"Connection refused" sur le frontend

Symptômes : Le navigateur affiche "Connection refused" sur http://localhost:3000

Causes possibles :

1. Conteneur frontend non démarré
2. Port proxy non configuré

Solutions :

# Vérifier le conteneur
docker ps | grep pch_frontend

# Si arrêté, redémarrer
docker start pch_frontend

# Vérifier le port proxy
netsh interface portproxy show v4tov4

# Reconfigurer si nécessaire
netsh interface portproxy add v4tov4 listenport=3000 listenaddress=0.0.0.0 connectport=80 connectaddress=192.168.99.100

"502 Bad Gateway" sur l'API

Symptômes : Les requêtes API retournent une erreur 502

Causes possibles :

1. Backend PHP non démarré
2. Nginx backend mal configuré

Solutions :

# Vérifier les conteneurs
docker ps | grep -E "(pch_backend|pch_nginx_backend)"

# Consulter les logs
docker logs pch_backend --tail 50
docker logs pch_nginx_backend --tail 50

# Redémarrer
docker restart pch_backend pch_nginx_backend

"401 Unauthorized"

Symptômes : Toutes les requêtes API retournent 401

Causes possibles :

1. Token JWT expiré
2. Clés JWT invalides

Solutions :

# Vérifier les clés JWT
docker exec pch_backend ls -la config/jwt/

# Régénérer les clés
docker exec pch_backend php bin/console lexik:jwt:generate-keypair --overwrite

# Vider le cache
docker exec pch_backend php bin/console cache:clear

---

Problèmes de base de données

"Connection refused" PostgreSQL

Symptômes : Erreur de connexion à la base de données

Solutions :

# Vérifier le conteneur
docker ps | grep pch_postgres

# Vérifier les logs
docker logs pch_postgres --tail 50

# Tester la connexion
docker exec pch_postgres psql -U pch_admin -d pch_sig -c "SELECT 1;"

"Relation does not exist"

Symptômes : Erreur "relation X does not exist"

Cause : Migrations non exécutées

Solution :

# Exécuter les migrations
docker exec pch_backend php bin/console doctrine:migrations:migrate --no-interaction

# Vérifier le schéma
docker exec pch_backend php bin/console doctrine:schema:validate

Base de données corrompue

# Vérifier l'intégrité
docker exec pch_postgres psql -U pch_admin -d pch_sig -c "
SELECT 'menages' as table_name, count(*) FROM menages
UNION ALL
SELECT 'beneficiaires', count(*) FROM beneficiaires
UNION ALL
SELECT 'paiements', count(*) FROM paiements;"

# Si problème, restaurer depuis sauvegarde
docker exec -i pch_postgres psql -U pch_admin -d pch_sig < backup.sql

---

Problèmes Docker

Docker Machine ne démarre pas

# Vérifier VirtualBox
& "C:\Program Files\Oracle\VirtualBox\VBoxManage.exe" list vms

# Démarrer manuellement
docker-machine start default

# Si erreur, régénérer les certificats
docker-machine regenerate-certs default

Conteneur en redémarrage continu

Symptômes : Conteneur avec status "Restarting"

# Voir les logs
docker logs pch_backend

# Causes courantes :
# - Erreur de configuration
# - Dépendance manquante
# - Permissions incorrectes

# Démarrer en mode interactif pour débugger
docker-compose run --rm backend bash

Espace disque insuffisant

# Vérifier l'espace
docker system df

# Nettoyer
docker system prune -a --volumes

---

Problèmes de performances

Application lente

Diagnostic :

# Vérifier l'utilisation des ressources
docker stats

# Requêtes PostgreSQL lentes
docker exec pch_postgres psql -U pch_admin -d pch_sig -c "
SELECT query, calls, mean_time, total_time
FROM pg_stat_statements
ORDER BY total_time DESC
LIMIT 10;"

Solutions :

# Vider le cache Redis
docker exec pch_redis redis-cli -a redis_secure_2025 FLUSHALL

# Optimiser PostgreSQL
docker exec pch_postgres psql -U pch_admin -d pch_sig -c "VACUUM ANALYZE;"

# Vider le cache Symfony
docker exec pch_backend php bin/console cache:clear --env=prod

Mémoire insuffisante

# Augmenter la mémoire du conteneur dans docker-compose.yml
services:
  backend:
    deploy:
      resources:
        limits:
          memory: 1G

---

Problèmes d'authentification

Impossible de se connecter

Vérifications :

# Vérifier que l'utilisateur existe
docker exec pch_postgres psql -U pch_admin -d pch_sig -c "
SELECT email, roles, is_active FROM users WHERE email = 'admin@pch-sig.sn';"

# Réinitialiser le mot de passe
docker exec pch_backend php bin/console app:reset-password admin@pch-sig.sn NouveauMotDePasse123!

Token JWT invalide

# Vérifier les clés
docker exec pch_backend ls -la config/jwt/

# Vérifier les permissions
docker exec pch_backend stat config/jwt/private.pem

# Régénérer
docker exec pch_backend php bin/console lexik:jwt:generate-keypair --overwrite

---

Problèmes frontend

Page blanche

Causes possibles :

1. Build manquant
2. Erreur JavaScript

Solutions :

# Vérifier le build
ls -la frontend/build/

# Reconstruire
cd frontend
npm run build

# Vérifier la console navigateur (F12)

Service Worker bloquant les mises à jour

// Forcer la mise à jour
// Dans la console du navigateur
navigator.serviceWorker.getRegistrations().then(function(registrations) {
    for(let registration of registrations) {
        registration.unregister();
    }
});

Ou incrémenter la version dans service-worker.js :

const CACHE_NAME = 'pch-sig-cache-v3';

Erreurs CORS

Symptômes : Erreur "CORS policy" dans la console

Solutions :

# Vérifier la configuration CORS
docker exec pch_backend cat .env | grep CORS

# Modifier si nécessaire
CORS_ALLOW_ORIGIN='^https?://(localhost|192\.168\.1\.*)(:[0-9]+)?$'

# Redémarrer
docker restart pch_backend

---

Problèmes de fichiers

Upload échoue

# Vérifier les permissions
docker exec pch_backend ls -la public/uploads/

# Corriger
docker exec pch_backend chown -R www-data:www-data public/uploads/
docker exec pch_backend chmod -R 775 public/uploads/

Fichiers non accessibles

# Vérifier le mapping de volumes
docker inspect pch_backend | grep -A 10 Mounts

# Vérifier que le fichier existe
docker exec pch_backend ls -la public/uploads/documents/

---

Commandes utiles

Redémarrer tout

docker-machine ssh default "cd /c/pch-sig/deploy && docker compose restart"

Vider tous les caches

docker exec pch_backend php bin/console cache:clear
docker exec pch_redis redis-cli -a redis_secure_2025 FLUSHALL

Réinitialiser complètement

# ATTENTION : Supprime toutes les données !
docker-machine ssh default "cd /c/pch-sig/deploy && docker compose down -v"
docker-machine ssh default "cd /c/pch-sig/deploy && docker compose up -d"

---

Obtenir de l'aide

Informations à fournir

Lorsque vous demandez de l'aide, incluez :

1. Description du problème
2. Étapes pour reproduire
3. Messages d'erreur complets
4. Logs pertinents :

   docker logs pch_backend --tail 100 > backend.log
   docker logs pch_postgres --tail 50 > postgres.log

5. État des conteneurs :

   docker ps -a > containers.txt

---

Prochaines étapes

• Logs
• Monitoring