Troubleshooting

This guide helps resolve common issues encountered with PCH-SIG.

Quick diagnosis

Check service status

# Container status
docker ps -a

# Application health
curl http://localhost:8000/api/health

Diagnostic script

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

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

# Containers
Write-Host "`n[Containers]"
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: ERROR" -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: ERROR" -ForegroundColor Red
}

---

Connection problems

"Connection refused" on frontend

Symptoms: Browser displays "Connection refused" at http://localhost:3000

Possible causes:

1. Frontend container not started
2. Port proxy not configured

Solutions:

# Check container
docker ps | grep pch_frontend

# If stopped, restart
docker start pch_frontend

# Check port proxy
netsh interface portproxy show v4tov4

# Reconfigure if needed
netsh interface portproxy add v4tov4 listenport=3000 listenaddress=0.0.0.0 connectport=80 connectaddress=192.168.99.100

"502 Bad Gateway" on API

Symptoms: API requests return 502 error

Possible causes:

1. PHP backend not started
2. Nginx backend misconfigured

Solutions:

# Check containers
docker ps | grep -E "(pch_backend|pch_nginx_backend)"

# Check logs
docker logs pch_backend --tail 50
docker logs pch_nginx_backend --tail 50

# Restart
docker restart pch_backend pch_nginx_backend

"401 Unauthorized"

Symptoms: All API requests return 401

Possible causes:

1. JWT token expired
2. Invalid JWT keys

Solutions:

# Check JWT keys
docker exec pch_backend ls -la config/jwt/

# Regenerate keys
docker exec pch_backend php bin/console lexik:jwt:generate-keypair --overwrite

# Clear cache
docker exec pch_backend php bin/console cache:clear

---

Database problems

"Connection refused" PostgreSQL

Symptoms: Database connection error

Solutions:

# Check container
docker ps | grep pch_postgres

# Check logs
docker logs pch_postgres --tail 50

# Test connection
docker exec pch_postgres psql -U pch_admin -d pch_sig -c "SELECT 1;"

"Relation does not exist"

Symptoms: Error "relation X does not exist"

Cause: Migrations not executed

Solution:

# Run migrations
docker exec pch_backend php bin/console doctrine:migrations:migrate --no-interaction

# Verify schema
docker exec pch_backend php bin/console doctrine:schema:validate

Corrupted database

# Check integrity
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;"

# If problem, restore from backup
docker exec -i pch_postgres psql -U pch_admin -d pch_sig < backup.sql

---

Docker problems

Docker Machine doesn't start

# Check VirtualBox
& "C:\Program Files\Oracle\VirtualBox\VBoxManage.exe" list vms

# Start manually
docker-machine start default

# If error, regenerate certificates
docker-machine regenerate-certs default

Container in continuous restart

Symptoms: Container with "Restarting" status

# View logs
docker logs pch_backend

# Common causes:
# - Configuration error
# - Missing dependency
# - Incorrect permissions

# Start in interactive mode for debugging
docker-compose run --rm backend bash

Insufficient disk space

# Check space
docker system df

# Clean up
docker system prune -a --volumes

---

Performance problems

Slow application

Diagnosis:

# Check resource usage
docker stats

# Slow PostgreSQL queries
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:

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

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

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

Insufficient memory

# Increase container memory in docker-compose.yml
services:
  backend:
    deploy:
      resources:
        limits:
          memory: 1G

---

Authentication problems

Cannot login

Checks:

# Verify user exists
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';"

# Reset password
docker exec pch_backend php bin/console app:reset-password admin@pch-sig.sn NewPassword123!

Invalid JWT token

# Check keys
docker exec pch_backend ls -la config/jwt/

# Check permissions
docker exec pch_backend stat config/jwt/private.pem

# Regenerate
docker exec pch_backend php bin/console lexik:jwt:generate-keypair --overwrite

---

Frontend problems

Blank page

Possible causes:

1. Missing build
2. JavaScript error

Solutions:

# Check build
ls -la frontend/build/

# Rebuild
cd frontend
npm run build

# Check browser console (F12)

Service Worker blocking updates

// Force update
// In browser console
navigator.serviceWorker.getRegistrations().then(function(registrations) {
    for(let registration of registrations) {
        registration.unregister();
    }
});

Or increment version in service-worker.js:

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

CORS errors

Symptoms: "CORS policy" error in console

Solutions:

# Check CORS configuration
docker exec pch_backend cat .env | grep CORS

# Modify if needed
CORS_ALLOW_ORIGIN='^https?://(localhost|192\.168\.1\.*)(:[0-9]+)?$'

# Restart
docker restart pch_backend

---

File problems

Upload fails

# Check permissions
docker exec pch_backend ls -la public/uploads/

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

Files not accessible

# Check volume mapping
docker inspect pch_backend | grep -A 10 Mounts

# Verify file exists
docker exec pch_backend ls -la public/uploads/documents/

---

Useful commands

Restart everything

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

Clear all caches

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

Complete reset

# WARNING: Deletes all data!
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"

---

Getting help

Information to provide

When asking for help, include:

1. Problem description
2. Steps to reproduce
3. Complete error messages
4. Relevant logs:

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

5. Container status:

   docker ps -a > containers.txt

---

Next steps

• Logs
• Monitoring