Mot de passe DB retiré (2026-07-04) — remplacé par [REDACTED], voir le vrai .env du serveur pour la valeur réelle.

Guide de déploiement — Backend ESM Caritas Bénin¶

Version : 2026-06-17
Projet : Plateforme de Suivi des Enfants Talibé (ProjetESM)
Backend : Node.js 20 + Express + TypeScript + Prisma + PostgreSQL natif
Port : 4100
Domaine : esm.tekdhi.dev

Vue d'ensemble¶

Le backend tourne dans un conteneur Docker avec --network host, ce qui lui permet d'accéder au PostgreSQL natif du VPS (non conteneurisé) à l'adresse 127.0.0.1:5432. Caddy joue le rôle de reverse proxy HTTPS.

Internet → Caddy (HTTPS) → 127.0.0.1:4100 (conteneur Docker)
                                    ↓
                        PostgreSQL natif 127.0.0.1:5432

Prérequis¶

Outils requis sur le VPS¶

Docker installé et démon actif (docker ps doit répondre)
PostgreSQL natif installé et démarré (sudo systemctl status postgresql)
Node.js 20+ disponible (pour prisma db push en local)

Fichiers en place (déjà créés)¶

Fichier	Emplacement
Configuration de déploiement	`/home/kanmaber/scripts/deploys/projetesm.env`
Script de déploiement	`/home/kanmaber/scripts/deploys/deploy.sh`
Dockerfile	`/home/kanmaber/projets/ProjetESM/BackEnd/Dockerfile`
Schéma Prisma	`/home/kanmaber/projets/ProjetESM/BackEnd/prisma/schema.prisma`
Seed RBAC + données initiales	`/home/kanmaber/projets/ProjetESM/BackEnd/prisma/seeds/seed.ts`

Étape 1 — Créer la base de données PostgreSQL¶

Cette étape est unique. Elle ne se répète pas lors des redéploiements.

Se connecter à PostgreSQL en tant que superutilisateur et créer l'utilisateur + la base :

sudo -u postgres psql <<'SQL'
CREATE USER esm_user WITH PASSWORD '[REDACTED]';
CREATE DATABASE esm_db OWNER esm_user;
GRANT ALL PRIVILEGES ON DATABASE esm_db TO esm_user;
SQL

Vérification :

sudo -u postgres psql -c "\l" | grep esm_db
# Doit afficher : esm_db | esm_user | UTF8 | ...

Étape 2 — Appliquer le schéma Prisma¶

IMPORTANT : Utiliser UNIQUEMENT prisma db push. Ne jamais utiliser prisma migrate dev — la shadow database n'existe pas sur ce VPS.

Se placer dans le répertoire BackEnd :

cd /home/kanmaber/projets/ProjetESM/BackEnd

Appliquer le schéma :

DATABASE_URL="postgresql://esm_user:[REDACTED]@127.0.0.1:5432/esm_db" \
  npx prisma db push

Résultat attendu :

Your database is now in sync with your Prisma schema.

Si des tables ont déjà été créées par un script SQL préalable (migration_phase1_creer_tables.sql), db push va les synchroniser sans les recréer. C'est sans danger.

Étape 3 — Générer le client Prisma¶

Cette étape est nécessaire une fois localement pour les vérifications TypeScript. Elle est automatisée dans le Dockerfile pour le build Docker.

cd /home/kanmaber/projets/ProjetESM/BackEnd
npx prisma generate

Résultat attendu :

Generated Prisma Client (v5.22.0) to ./../node_modules/@prisma/client in XXXms

Sans cette étape, npx tsc --noEmit retourne 35 erreurs TS2305 (membres de @prisma/client absents). Elle est automatiquement exécutée dans le Dockerfile avant la compilation.

Étape 4 — Seeder les données initiales¶

Le seed insère les données de référence et la matrice RBAC complète. Il est idempotent (utilise upsert — peut être relancé sans risque).

Données insérées par le seed : - 3 communes initiales (N'Dali, Kandi, Malanville) - 8 types d'accompagnement (Formation artisanale, Scolarisation, Soutien psychosocial…) - 5 profils officiels (AGENT_TERRAIN, MEAL_COMMUNAL, MEAL_NATIONAL, CHARGE_PROJET, ADMIN) - 30+ permissions (ENFANT_LIRE, ACCOMPAGNEMENT_CREER, AUDIT_LIRE…) - Matrice permissions × profils complète

Lancer le seed :

cd /home/kanmaber/projets/ProjetESM/BackEnd
DATABASE_URL="postgresql://esm_user:[REDACTED]@127.0.0.1:5432/esm_db" \
  npx tsx prisma/seeds/seed.ts

Résultat attendu (extrait) :

Demarrage du seed...
Commune : N'Dali
Commune : Kandi
...
Permission : ENFANT_LIRE
...
Liaisons ADMIN : 30 permissions
Seed termine avec succes !

Étape 5 — Vérification TypeScript (optionnel avant déploiement)¶

Pour s'assurer que la compilation est propre avant de lancer Docker :

cd /home/kanmaber/projets/ProjetESM/BackEnd
npm install        # si node_modules absent
npx prisma generate  # si pas encore fait
npx tsc --noEmit
# Doit retourner : (aucune sortie) + exit code 0

Étape 6 — Déployer le backend¶

Lancer le script de déploiement avec la cible backend :

bash /home/kanmaber/scripts/deploys/deploy.sh \
  --config /home/kanmaber/scripts/deploys/projetesm.env \
  --target backend

Ce que fait le script, dans l'ordre : 1. docker build — construit l'image ProjetESM-backend:latest 2. docker stop + docker rm — arrête et supprime l'ancien conteneur 3. docker run — démarre le nouveau conteneur avec toutes les variables d'environnement 4. Attend 5 secondes 5. Teste http://localhost:4100/_health puis /health

Ce que fait le Dockerfile en détail¶

FROM node:20-alpine
RUN apk add --no-cache openssl          # requis par Prisma sur Alpine

WORKDIR /app

COPY BackEnd/package*.json ./BackEnd/
RUN npm ci --prefix ./BackEnd           # installe toutes les dépendances

COPY BackEnd/prisma ./BackEnd/prisma
RUN cd ./BackEnd && npx prisma generate # génère @prisma/client (types + requêtes)

COPY BackEnd/ ./BackEnd/
RUN npm --prefix ./BackEnd run build    # tsc → compile src/ vers dist/

WORKDIR /app/BackEnd
EXPOSE 4100
CMD ["npm", "start"]
# npm start = node -r tsconfig-paths/register dist/server.js
# Le flag -r tsconfig-paths/register résout les alias @/ au runtime

Le build context Docker est PROJECT_DIR (/home/kanmaber/projets/ProjetESM/), pas le répertoire BackEnd seul. C'est pour que le Dockerfile puisse COPY BackEnd/....

Variables d'environnement injectées dans le conteneur¶

Variable	Valeur	Description
`NODE_ENV`	`production`	Mode Node
`PORT`	`4100`	Port d'écoute
`DATABASE_URL`	`postgresql://esm_user:[REDACTED]@127.0.0.1:5432/esm_db`	Connexion PostgreSQL natif
`JWT_ACCESS_SECRET`	`c906400b...`	Secret JWT access token (24h)
`JWT_REFRESH_SECRET`	`75487650...`	Secret JWT refresh token (7j)
`JWT_ACCESS_EXPIRES`	`24h`	Durée access token
`JWT_REFRESH_EXPIRES`	`7d`	Durée refresh token
`CORS_ORIGIN`	`https://esm.tekdhi.dev`	Origine autorisée CORS
`APP_NAME`	`ESM-Caritas-Benin`	Nom de l'application
`APP_URL`	`https://esm.tekdhi.dev`	URL publique
`REDIS_HOST`	`127.0.0.1`	Redis (fallback InMemory si absent)
`REDIS_PORT`	`6379`	Port Redis

Redis : Le serveur démarre normalement même si Redis est absent. Il bascule automatiquement en mode InMemory (__REDIS_AVAILABLE__ = false). BullMQ ne sera pas disponible mais aucune erreur fatale n'est levée.

Étape 7 — Vérifier que le backend est opérationnel¶

Health check¶

curl -s http://localhost:4100/health | python3 -m json.tool

Réponse attendue :

{
  "succes": true,
  "message": "ESM Caritas Benin — serveur opérationnel",
  "timestamp": "2026-06-17T...",
  "version": "...",
  "endpoints": {
    "health": "/health",
    "api": "/api/v1"
  }
}

Si la réponse est absente :

docker logs ProjetESM-backend --tail 30

Tester une route d'API¶

curl -s http://localhost:4100/api/v1/auth/status | python3 -m json.tool

Étape 8 — Surveiller les logs en temps réel¶

docker logs ProjetESM-backend --tail 50 --follow

Sortie normale au démarrage :

[Redis] INDISPONIBLE (fallback InMemory) - ...
Initialisation des dépendances...
Auto-discovery : X routes chargées (Y modules)
Serveur ESM démarré sur le port 4100

Redéploiement (mise à jour du code)¶

À chaque modification du code backend :

# 1. Commiter les changements (git)
cd /home/kanmaber/projets/ProjetESM
git add BackEnd/
git commit -m "description des changements"

# 2. Relancer le déploiement backend uniquement
bash /home/kanmaber/scripts/deploys/deploy.sh \
  --config /home/kanmaber/scripts/deploys/projetesm.env \
  --target backend

# 3. Vérifier
curl -s http://localhost:4100/health

Si le schéma Prisma a changé (modification de schema.prisma) :

# AVANT le redéploiement Docker
DATABASE_URL="postgresql://esm_user:[REDACTED]@127.0.0.1:5432/esm_db" \
  npx prisma db push

# Ensuite redéployer normalement
bash /home/kanmaber/scripts/deploys/deploy.sh \
  --config /home/kanmaber/scripts/deploys/projetesm.env \
  --target backend

Déploiement complet (backend + frontend + Caddy)¶

Pour la mise en production complète (première fois ou après changement frontend) :

bash /home/kanmaber/scripts/deploys/deploy.sh \
  --config /home/kanmaber/scripts/deploys/projetesm.env \
  --target both

Cela exécute dans l'ordre : 1. Build et démarrage du conteneur backend 2. npm ci + npm run build du frontend Vite 3. Copie du dist/ vers /home/kanmaber/frontESM/ 4. Mise à jour du bloc Caddy pour esm.tekdhi.dev 5. Redémarrage du conteneur caddy-host

Troubleshooting¶

Le conteneur ne démarre pas¶

docker logs ProjetESM-backend --tail 50
# Chercher : "Error", "ECONNREFUSED", "Cannot find module"

Erreur de connexion à la base de données¶

# Tester la connexion manuellement
psql "postgresql://esm_user:[REDACTED]@127.0.0.1:5432/esm_db" -c "\dt"
# Si échec : vérifier que PostgreSQL est démarré
sudo systemctl status postgresql
sudo systemctl start postgresql

Erreur "Cannot find module '@/...'"¶

Le flag -r tsconfig-paths/register n'est pas dans le script de démarrage. Vérifier BackEnd/package.json :

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

Erreur Prisma "Unknown arg" ou types manquants¶

prisma generate n'a pas été exécuté ou le client est périmé.

cd BackEnd && npx prisma generate
# Puis redéployer

Erreur "Module '@prisma/client' has no exported member 'StatutAccompagnement'"¶

Même cause : le client Prisma n'est pas généré. Le Dockerfile l'exécute automatiquement, donc ce problème n'apparaît qu'en vérification locale. Solution : npx prisma generate.

Le health check répond "connection refused"¶

Le conteneur n'a pas encore démarré. Attendre 10 secondes et réessayer :

sleep 10 && curl -s http://localhost:4100/health

Vérifier l'état du conteneur¶

docker ps | grep ProjetESM
# Doit afficher le conteneur avec status "Up X seconds"

Récapitulatif — Première mise en service¶

# 1. Créer la base de données (une seule fois)
sudo -u postgres psql -c "CREATE USER esm_user WITH PASSWORD '[REDACTED]';"
sudo -u postgres psql -c "CREATE DATABASE esm_db OWNER esm_user;"
sudo -u postgres psql -c "GRANT ALL PRIVILEGES ON DATABASE esm_db TO esm_user;"

# 2. Appliquer le schéma
cd /home/kanmaber/projets/ProjetESM/BackEnd
DATABASE_URL="postgresql://esm_user:[REDACTED]@127.0.0.1:5432/esm_db" npx prisma db push

# 3. Seeder les données initiales
DATABASE_URL="postgresql://esm_user:[REDACTED]@127.0.0.1:5432/esm_db" npx tsx prisma/seeds/seed.ts

# 4. Déployer le backend
bash /home/kanmaber/scripts/deploys/deploy.sh --config /home/kanmaber/scripts/deploys/projetesm.env --target backend

# 5. Vérifier
curl -s http://localhost:4100/health