Troubleshooting

Container unhealthy ou en redemarrage

Diagnostic

# Verifier l'etat des containers
docker ps -a --format "table \t"

# Inspecter le healthcheck d'un container
docker inspect --format='' raci-flow-app | python3 -m json.tool

# Consulter les logs
docker logs raci-flow-app --tail 100

L’application ne demarre pas

Symptome : raci-flow-app reste en starting ou unhealthy.

Causes possibles :

1. PostgreSQL pas encore ready : L’application depend de postgres avec condition: service_healthy. Verifier que postgres est sain :

   docker inspect --format='' raci-flow-postgres
   

2. Variable d’environnement manquante : Le serveur refuse de demarrer si JWT_SECRET n’est pas defini en production.

   docker logs raci-flow-app 2>&1 | grep "FATAL"
   

3. Port 3000 occupe : Le serveur tente les ports 3000 a 3019. Verifier avec :

   docker exec raci-flow-app netstat -tlnp
   

PostgreSQL ne demarre pas

Symptome : raci-flow-postgres en unhealthy.

# Verifier les logs PostgreSQL
docker logs raci-flow-postgres --tail 50

# Verifier l'espace disque
df -h
docker system df

Cause frequente : Espace disque insuffisant sur le volume postgres_data.

Redis ne demarre pas

docker logs raci-flow-redis --tail 50

Redis en mode AOF (--appendonly yes) peut echouer si le fichier AOF est corrompu :

docker exec raci-flow-redis redis-check-aof --fix /data/appendonly.aof

Erreurs Sentry

Consulter les erreurs recentes

Acceder au tableau de bord Sentry de l’organisation na-vln :

• Backend : projet raciflow-backend
• Frontend : projet raciflow-frontend

Erreurs frequentes

Erreur	Cause probable	Resolution
DATABASE_URL is required	Variable d’environnement manquante	Verifier le fichier .env
FATAL: JWT_SECRET must be set	Secret JWT absent en production	Ajouter JWT_SECRET dans .env
Connection refused (PostgreSQL)	Container postgres down ou reseau	Verifier docker ps et le reseau internal
TRPC_INTERNAL_SERVER_ERROR	Erreur non geree cote serveur	Consulter les logs et le detail dans Sentry

Migrations de base de donnees

Appliquer les migrations

docker exec raci-flow-app npx drizzle-kit generate
docker exec raci-flow-app npx drizzle-kit migrate

Migration echouee

1. Verifier le detail de l’erreur :

   docker exec raci-flow-app npx drizzle-kit migrate 2>&1
   

2. Si une migration est partiellement appliquee, inspecter l’etat de la base :

   docker exec raci-flow-postgres psql -U raci_user -d raci_flow -c "\dt"
   

3. Verifier la table de suivi des migrations Drizzle :

   docker exec raci-flow-postgres psql -U raci_user -d raci_flow \
     -c "SELECT * FROM __drizzle_migrations ORDER BY created_at DESC LIMIT 5;"
   

Rollback manuel

Drizzle ne propose pas de rollback automatique. En cas de probleme :

1. Restaurer un backup PostgreSQL (voir backup-restore.md)
2. Corriger le schema dans le code source
3. Regenerer et reappliquer les migrations

Rebuild Docker complet

Rebuild sans cache

cd /root/home-it/apps/raci-flow
docker compose build --no-cache
docker compose up -d

Nettoyage des images et volumes inutilises

# Supprimer les images non utilisees
docker image prune -f

# Supprimer les volumes orphelins (ATTENTION: perte de donnees potentielle)
docker volume prune -f

# Nettoyage complet (images, containers, reseaux)
docker system prune -f

Attention : Ne jamais utiliser docker volume prune sans verifier que postgres_data et redis_data ne seront pas supprimes.

Recreer un container specifique

cd /root/home-it/apps/raci-flow
docker compose up -d --force-recreate app

Problemes reseau

Le site n’est pas accessible

1. Verifier que Caddy est en cours d’execution :

   docker ps --filter name=caddy-proxy
   

2. Verifier la configuration Caddy :

   docker exec caddy-proxy caddy validate --config /etc/caddy/Caddyfile
   

3. Verifier que le reseau proxy existe et connecte les bons containers :

   docker network inspect proxy
   

4. Tester la connectivite interne :

   docker exec caddy-proxy wget -qO- http://raci-flow-app:3000
   

Certificat TLS expire ou invalide

Caddy renouvelle automatiquement les certificats. Si un probleme survient :

# Verifier les logs Caddy
docker logs caddy-proxy --tail 50 | grep -i "tls\|cert\|acme"

# Forcer le renouvellement en redemarrant Caddy
cd /root/home-it/vps/proxy
docker compose restart caddy