Erreurs de déploiement résolues — gestionFichePaie¶

Session : 20260515 — premier déploiement VPS du projet gestionFichePaie (monorepo DDD_Module)

1. shared-kernel ESM incompatible avec backend CJS¶

Symptôme : SyntaxError: Cannot use import statement in a module ou erreur silencieuse à l'import.

Cause : shared-kernel compilait en ESM ("module": "ES2020" + "type": "module"). Le backend tourne en CommonJS.

Fix : - shared-kernel/tsconfig.json → "module": "CommonJS" - shared-kernel/package.json → supprimer "type": "module" - Committer shared-kernel/dist/ dans git (ne pas le rebuilder dans Docker)

2. PostgreSQL lowercase les rôles non-quotés¶

Symptôme : role "fichePaie_user" does not exist alors que le rôle a été créé avec ce nom.

Cause : PostgreSQL normalise en minuscules les identifiants non-quotés. CREATE USER fichePaie_user crée fichepaie_user.

Fix : utiliser le nom en minuscules dans DATABASE_URL :

postgresql://fichepaie_user:motdepasse@shared-postgres:5432/gestionFichePaie

3. Syntaxe npm --prefix¶

Symptôme : npm run build --prefix ./BackEnd ignore le prefix et cherche package.json à la racine.

Fix : l'ordre est inversé —

# Correct
npm --prefix ./BackEnd run build

# Incorrect (ne fonctionne pas)
npm run build --prefix ./BackEnd

4. Alias @/ non résolus au runtime avec tsconfig-paths¶

Symptôme : Cannot find module '@/shared/...' au démarrage du serveur compilé.

Cause : tsc-alias réécrit les imports à la compilation, mais tsconfig-paths est nécessaire pour les résoudre à runtime via -r.

Fix dans package.json :

"start": "node -r tsconfig-paths/register dist/server.js"

Et dans tsconfig.json, pointer vers les dist (pas src) :

"@shared/*": ["../shared-kernel/dist/*"]

5. CORS_ORIGIN obligatoire en production¶

Symptôme : /_health retourne {"message":"Configuration serveur invalide"} même si le serveur tourne.

Cause : le middleware CORS lit CORS_ORIGIN depuis l'env. Si absent en production, il bloque toutes les requêtes, y compris le health check.

Fix : ajouter dans docker run :

-e CORS_ORIGIN=*

7. Caddy : SIGHUP inefficace avec `admin off`¶

Symptôme : après modification du Caddyfile, docker kill --signal=SIGHUP caddy semble fonctionner mais l'ancienne config reste active (ex: file_server au lieu de reverse_proxy).

Cause : avec admin off dans le Caddyfile, l'API d'administration de Caddy est désactivée. Le SIGHUP tente de recharger via cette API — elle est absente, le rechargement échoue silencieusement.

Fix : toujours recharger avec :

docker restart caddy

6. Health check interne = port interne du container¶

Symptôme : docker exec health check échoue alors que le container répond sur le port externe.

Cause : à l'intérieur du container, le serveur écoute sur le port interne (ex: 3000), pas sur le port exposé (ex: 3902). Le mapping -p 3902:3000 est externe.

Fix :

# Correct — port interne
wget -qO- http://localhost:3000/health

# Incorrect — port externe (inaccessible depuis l'intérieur)
wget -qO- http://localhost:3902/health