UMHMA — Guide d'installation et de déploiement

Ce document explique comment cloner, installer, lancer et déployer le projet UMHMA. Il s'adresse aux contributeurs et aux personnes qui reprennent la maintenance.

---

1. Aperçu du projet

Le projet est un monorepo composé de deux applications :

Dossier	Rôle	Technologies
backend/	API REST + logique métier	Node.js 20, Express, PostgreSQL
frontend/	Interface utilisateur	React 18 (Create React App)

Les deux sont déployés ensemble sur une instance EC2 via GitHub Actions.

---

2. Prérequis

Avant de commencer, assure-toi d'avoir :

• Git ≥ 2.30
• Node.js 20 (installé via nvm recommandé)
• npm ≥ 9 (livré avec Node)
• PostgreSQL ≥ 14 (local ou managé)
• Un compte GitHub avec accès au dépôt
• (Optionnel) un compte Mailjet pour le formulaire de contact

Vérifie ta version de Node :

node -v   # doit afficher v20.x.x
npm -v

---

3. Cloner le projet

git clone git@github.com:Yayabtw/ProjectLabUMHMA.git
cd ProjectLabUMHMA

Si tu n'as pas encore de clé SSH GitHub, utilise plutôt l'URL HTTPS :

git clone https://github.com/Yayabtw/ProjectLabUMHMA.git

L'arborescence à la racine doit ressembler à :

ProjectLabUMHMA/
├── backend/
├── frontend/
├── docs/
├── diagrams/
├── scripts/
└── README.md

---

4. Configuration des variables d'environnement

Chaque application a son propre fichier .env, basé sur l'exemple env.example fourni.

4.1 Backend (backend/.env)

cd backend
cp env.example .env

Puis ouvre .env et renseigne :

Variable	Description
PORT	Port d'écoute de l'API (défaut : 4000)
JWT_SECRET	Clé secrète JWT — au moins 32 caractères
DATABASE_URL	Chaîne de connexion Postgres (postgres://user:pass@host:5432/db)
CORS_ALLOWED_ORIGINS	Origines autorisées, séparées par virgule (ex. http://localhost:3000)
PGSSLMODE	Décommenter et passer à require si l'hébergeur Postgres exige du SSL
MAILJET_*	Clés Mailjet pour le formulaire de contact (optionnel en dev)

⚠️ Le serveur refuse de démarrer si JWT_SECRET fait moins de 32 caractères. C'est volontaire pour éviter de pousser un secret faible en prod.

4.2 Frontend (frontend/.env)

cd ../frontend
cp env.example .env

Variable	Description
REACT_APP_API_URL	URL de l'API backend (défaut : http://localhost:4000)

---

5. Base de données

5.1 Créer la base en local

Avec Postgres installé localement :

createdb umhma_dev
psql umhma_dev -c "CREATE USER umhma WITH PASSWORD 'umhma'; GRANT ALL PRIVILEGES ON DATABASE umhma_dev TO umhma;"

Mets ensuite ta DATABASE_URL à jour :

DATABASE_URL=postgres://umhma:umhma@localhost:5432/umhma_dev

5.2 Migrations

Les tables sont créées automatiquement au premier démarrage du backend via le script src/services/dbInit.js. Aucune commande de migration manuelle n'est nécessaire.

---

6. Installer les dépendances

Depuis la racine du projet :

# Backend
cd backend
npm ci

# Frontend
cd ../frontend
npm ci

npm ci est préférable à npm install : il respecte strictement le package-lock.json et évite de modifier le lockfile par erreur.

---

7. Lancer le projet en local

Ouvre deux terminaux :

Terminal 1 — Backend

cd backend
npm run dev

Le serveur démarre sur http://localhost:4000. Vérifie qu'il répond :

curl http://localhost:4000/healthz

Terminal 2 — Frontend

cd frontend
npm start

Le navigateur s'ouvre automatiquement sur http://localhost:3000.

---

8. Tests

Backend

cd backend
npm test

Frontend

cd frontend
npm test -- --watchAll=false

---

9. Comptes administrateur

Pour accéder à l'interface admin (/admin), un compte doit avoir le flag is_admin. Promotion d'un utilisateur existant en SQL :

INSERT INTO admin (uuid_admin)
SELECT uuid_user FROM user_account WHERE email = 'ton.email@exemple.fr';

L'utilisateur doit ensuite se déconnecter / reconnecter pour que la session embarque le flag.

---

10. Déploiement automatique (CI/CD)

Le projet est déployé en continu sur AWS EC2 via GitHub Actions. Le workflow se trouve dans .github/workflows/deploy.yml.

10.1 Déclencheurs

Événement	Comportement
Pull request vers main	Tests backend + frontend uniquement
Push sur main	Tests → build frontend → déploiement EC2

10.2 Étapes du workflow

┌──────────┐   ┌────────────────┐   ┌──────────────────┐
│  test    │──▶│ build-frontend │──▶│ deploy + health  │
│ (matrix) │   │  (artefact)    │   │  (SSH → EC2)     │
└──────────┘   └────────────────┘   └──────────────────┘

1. test — exécute npm test pour backend et frontend en parallèle.
2. build-frontend — npm run build avec REACT_APP_API_URL injecté depuis les secrets, puis upload de l'artefact frontend/build/.
3. deploy :
   • télécharge l'artefact frontend ;
   • se connecte en SSH à l'EC2 (webfactory/ssh-agent) ;
   • sur le serveur : git fetch && git reset --hard origin/main, npm ci --omit=dev, pm2 restart umhma-api ;
   • synchronise le build front avec rsync --delete vers /var/www/umhma/frontend/build/ ;
   • exécute deux healthchecks (API /healthz, Frontend /).

10.3 Secrets GitHub requis

À configurer dans Settings → Secrets and variables → Actions du dépôt :

Secret	Description
SSH_PRIVATE_KEY	Clé privée SSH autorisée sur l'EC2
SSH_USER	Utilisateur SSH (ex. ubuntu)
SSH_HOST	Adresse de l'EC2 (IP ou DNS)
REACT_APP_API_URL	URL publique de l'API utilisée au build du front

10.4 Suivi d'un déploiement

1. Onglet Actions du dépôt → workflow CI/CD UMHMA.
2. Cliquer sur le run en cours pour voir les logs en direct.
3. Si le Healthcheck API échoue : se connecter à l'EC2 et inspecter PM2 :

ssh ubuntu@<SSH_HOST>
pm2 status
pm2 logs umhma-api --lines 100

10.5 Rollback rapide

Sur l'EC2, repartir d'un commit antérieur :

cd /var/www/umhma
git log --oneline -n 10
git reset --hard <sha-précédent>
cd backend && npm ci --omit=dev
pm2 restart umhma-api --update-env

Pour le front, il suffit de relancer le workflow GitHub Actions sur le commit voulu (Re-run all jobs).

---

11. Dépannage rapide

Problème	Piste de résolution
JWT_SECRET must be at least 32 characters	Allonger la valeur dans backend/.env
Front affiche Network Error	Vérifier REACT_APP_API_URL et que le backend tourne
CORS error dans la console navigateur	Ajouter l'origine du front dans CORS_ALLOWED_ORIGINS
pm2: command not found sur EC2	npm i -g pm2
Healthcheck CI échoue	pm2 logs umhma-api, vérifier que le port 4000 est ouvert