diff options
Diffstat (limited to 'DOC_TECHNIQUE.md')
| -rw-r--r-- | DOC_TECHNIQUE.md | 327 |
1 files changed, 327 insertions, 0 deletions
diff --git a/DOC_TECHNIQUE.md b/DOC_TECHNIQUE.md index 954cfb1..fd8e041 100644 --- a/DOC_TECHNIQUE.md +++ b/DOC_TECHNIQUE.md @@ -19,6 +19,26 @@ Ports principaux : - `9000` : backend (API + admin)
- `6379` : redis
+## 1.1) Redis (pourquoi et comment)
+
+Redis est une base cle-valeur en memoire, utilisee pour :
+- **cache** : accelerer certaines lectures.
+- **event bus** : diffuser des evenements internes (ex: `order.created`).
+- **queue legere** : traitement asynchrone simple.
+
+Dans ce projet, Medusa utilise :
+- `@medusajs/event-bus-redis` (event bus)
+- `@medusajs/cache-redis` (cache)
+
+Flux simple :
+1) Une action se produit (ex: produit cree).
+2) Medusa emet un evenement.
+3) Redis relaie l'evenement aux modules abonnes.
+
+Ou le voir :
+- `backend/medusa-config.js` -> `eventBus` et `cacheService`.
+- `docker-compose.yml` -> service `redis`.
+
## 2) Technologies utilisees (liens utiles)
- MedusaJS : https://docs.medusajs.com/
@@ -37,6 +57,68 @@ Ports principaux : - `.env` : variables d'environnement (non versionne).
- `env-example` : modele de variables d'environnement.
+## 3.1) D'ou vient le code (YAML vs depot)
+
+Le fichier `docker-compose.yml` **ne contient pas le code** :
+- il **decrit** comment lancer les conteneurs (services, ports, variables).
+- le **code** vient du depot Git (`backend/` et `storefront/`).
+
+Flux reel :
+1) On recupere le code via Git.
+2) `docker compose build` construit les images depuis les Dockerfile.
+3) `docker compose up` lance les conteneurs avec les variables `.env`.
+
+## 3.2) Medusa (backend) - installation technique
+
+Etapes principales :
+1) `backend/Dockerfile` copie `package.json`, installe les deps.
+2) `postinstall` lance `scripts/patch-medusa.js` (patch TypeORM).
+3) Le code est copie dans l'image.
+4) Le conteneur demarre `medusa start`.
+5) Connexion a PostgreSQL via `DATABASE_URL`.
+6) Connexion a Redis pour cache/event bus.
+
+Medusa tourne bien avec **Node.js** (runtime JavaScript).
+
+Briques logicielles principales :
+- **Node.js** : runtime qui execute Medusa.
+- **Express** : serveur HTTP sous-jacent.
+- **TypeORM** : ORM pour PostgreSQL.
+- **PostgreSQL** : base de donnees principale.
+- **Redis** : cache + event bus.
+- **MedusaJS** : API ecommerce (services, modules, plugins).
+
+## 3.3) Storefront (frontend) - fonctionnement
+
+- Next.js compile le site au build (`npm run build`).
+- La variable `NEXT_PUBLIC_MEDUSA_BACKEND_URL` est **injectee au build**.
+- Le conteneur expose le site sur le port `8000`.
+
+## 3.4) Schema technique (ASCII)
+
+```
+ +----------------------+
+ | Storefront |
+ | Next.js (Node) |
+ | :8000 |
+ +----------+-----------+
+ |
+ | HTTP (API)
+ v
+ +----------------------+
+ | MedusaJS |
+ | Node + Express |
+ | :9000 (API/Admin) |
+ +-----+----------+-----+
+ | |
+ SQL | | Cache/Event bus
+ v v
+ +---------------+ +----------------+
+ | PostgreSQL | | Redis |
+ | :5432 | | :6379 |
+ +---------------+ +----------------+
+```
+
## 4) Installation rapide (serveur)
1. Copier la configuration :
@@ -59,6 +141,39 @@ COOKIE_SECRET=change_me docker compose up -d --build
```
+### 4.1) Exemple reel (ce que nous avons fait)
+
+Contexte : backend sur `192.168.99.22:9000`, storefront sur `192.168.99.22:8000`.
+
+1) Variables d'environnement (exemple utilise) :
+```
+DATABASE_URL=postgres://luciensbdb:********@192.168.99.35:5432/sens_bon_db
+JWT_SECRET=supersecret
+COOKIE_SECRET=supersecret
+ADMIN_CORS=http://192.168.99.22:9000
+STORE_CORS=http://192.168.99.22:8000
+NEXT_PUBLIC_MEDUSA_BACKEND_URL=http://192.168.99.22:9000
+NODE_ENV=development
+```
+
+2) Rebuild complet (pour appliquer les patches) :
+```
+sudo docker compose build --no-cache backend
+sudo docker compose up -d backend
+sudo docker compose up -d --build storefront
+```
+
+3) Verification rapide :
+```
+curl -v http://localhost:9000/store/products
+curl -v http://192.168.99.22:8000
+```
+
+4) Seed (donnees demo) :
+```
+sudo docker compose run --rm backend npm run seed
+```
+
## 5) Tests rapides
Verifier que les conteneurs tournent :
@@ -82,6 +197,59 @@ docker compose logs -f backend docker compose logs -f storefront
```
+### 5.1) Logs systeme avec journalctl (systemd)
+
+Utiliser `journalctl` pour diagnostiquer les services systeme (Apache, dnsmasq, Docker).
+
+Ou sont stockes les logs systeme :
+- **Persistant** : `/var/log/journal/` (apres reboot)
+- **Volatile** : `/run/log/journal/` (perdu au reboot)
+
+Verifier le stockage et la retention :
+```
+sudo journalctl --disk-usage
+sudo journalctl --list-boots
+```
+
+Options courantes (rappel rapide) :
+- `-u <service>` : filtre sur un service (ex: `dnsmasq`, `apache2`, `docker`)
+- `-n N` : N dernieres lignes
+- `-f` : suivi en direct (tail -f)
+- `-b` : logs du dernier boot
+- `-o short|short-iso` : format de sortie
+- `-S "<date>"` : depuis une date/heure (ex: `"10 min ago"`)
+- `--no-pager` : pas de pagination
+
+Exemples utiles :
+```
+# 50 derniers logs dnsmasq
+sudo journalctl -u dnsmasq -n 50 --no-pager
+
+# Logs Apache en direct
+sudo journalctl -u apache2 -f
+
+# Logs Docker (service systemd)
+sudo journalctl -u docker -n 100 --no-pager
+
+# Logs depuis le dernier boot
+sudo journalctl -b -u dnsmasq --no-pager
+
+# Logs avec horodatage court
+sudo journalctl -u dnsmasq -n 50 --no-pager -o short
+
+# Derniers logs "pousses" (ecrits recemment)
+sudo journalctl -n 50 --no-pager
+sudo journalctl -u dnsmasq -S "10 min ago" --no-pager
+```
+
+### 5.2) Tests CORS (exemple utilise)
+
+```
+curl -i -H "Origin: http://192.168.99.22:8000" http://192.168.99.22:9000/store/products
+```
+
+- Confirme que `Access-Control-Allow-Origin` autorise le storefront.
+
## 6) Ou se trouve la base de donnees ?
Le backend lit la base de donnees via `DATABASE_URL` dans `.env`.
@@ -112,6 +280,93 @@ Le storefront attend l'API backend. Verifier : - `NEXT_PUBLIC_MEDUSA_BACKEND_URL` dans `.env`
- le backend repond sur `:9000`
+Si le backend repond, mais que rien ne s'affiche :
+- verifier que le storefront a ete **rebuild** apres changement de `.env` :
+```
+sudo docker compose up -d --build storefront
+```
+- verifier que `storefront/pages/_app.js` utilise
+`process.env.NEXT_PUBLIC_MEDUSA_BACKEND_URL` (pas `localhost` en dur).
+
+### Admin Medusa (login qui boucle)
+
+Symptome : l'admin reste sur la page de login.
+Cause frequente : cookies `Secure` bloques en HTTP si `NODE_ENV=production`.
+
+Solution appliquee :
+1) Rendre `NODE_ENV` configurable dans `docker-compose.yml`.
+2) Mettre `NODE_ENV=development` dans `.env`.
+3) Rebuild backend :
+```
+sudo docker compose up -d --build backend
+```
+
+### CORS admin/storefront (procedure)
+
+Objectif : autoriser le navigateur a appeler l'API depuis le storefront et l'admin.
+
+1) Verifier `.env` :
+```
+ADMIN_CORS=http://<IP_DU_SERVEUR>:9000
+STORE_CORS=http://<IP_DU_SERVEUR>:8000
+```
+
+2) Rebuild backend pour appliquer les variables :
+```
+sudo docker compose up -d --build backend
+```
+
+3) Test CORS (storefront) :
+```
+curl -i -H "Origin: http://<IP_DU_SERVEUR>:8000" http://<IP_DU_SERVEUR>:9000/store/products
+```
+
+### Admin en HTTP (procedure NODE_ENV)
+
+Objectif : eviter le blocage des cookies `Secure` en HTTP.
+
+1) Rendre `NODE_ENV` configurable dans `docker-compose.yml` :
+```
+NODE_ENV=${NODE_ENV}
+```
+
+2) Dans `.env` :
+```
+NODE_ENV=development
+```
+
+3) Rebuild backend :
+```
+sudo docker compose up -d --build backend
+```
+
+### Patch Medusa (TypeORM update vide)
+
+Probleme :
+- Erreur TypeORM `Empty criteria(s) are not allowed for the update method`.
+- Medusa appelle `update({}, { is_installed: false })` sans criteres.
+
+Correctif applique :
+1) Script de patch : `backend/scripts/patch-medusa.js`
+2) Execution automatique : `postinstall` dans `backend/package.json`
+3) Dockerfile : `COPY scripts ./scripts` avant `npm install`
+
+Fichiers Medusa patches :
+- `node_modules/@medusajs/medusa/dist/services/payment-provider.js`
+- `node_modules/@medusajs/medusa/dist/services/notification.js`
+- `node_modules/@medusajs/medusa/dist/services/fulfillment-provider.js`
+- `node_modules/@medusajs/medusa/dist/services/tax-provider.js`
+
+Remplacement effectue (exemple) :
+- Avant : `model.update({}, { is_installed: false })`
+- Apres : `model.createQueryBuilder().update().set({ is_installed: false }).where('1=1').execute()`
+
+Rebuild obligatoire pour appliquer le patch :
+```
+sudo docker compose build --no-cache backend
+sudo docker compose up -d backend
+```
+
## 8) Mise en production (reverse proxy)
Pour exposer en HTTP/HTTPS, utiliser Apache ou Nginx. Exemple Apache :
@@ -178,3 +433,75 @@ docker compose up -d --build - Garder un backup hors serveur (S3, autre machine).
- Tester les restaurations une fois par trimestre.
+## 11) Procedure Git (push + alignement serveur)
+
+Objectif : pousser le code vers `chillka`, puis aligner `huitral` **sans perdre de changements**.
+
+### 11.1 Depuis votre machine de dev
+```
+git status
+git add -A
+git commit -m "feat: mise a jour storefront + checkout"
+git push origin main
+```
+Explication rapide :
+- `git status` : voir les fichiers modifies.
+- `git add -A` : ajouter tous les changements a l'index.
+- `git commit -m "..."` : creer un snapshot local.
+- `git push origin main` : envoyer le snapshot sur chillka (branche `main`).
+
+### 11.2 Sur `huitral` avec changements locaux
+Option recommandee (garder les changements) :
+```
+cd /var/www/lucien-sens-bon
+git status
+git add -A
+git commit -m "wip: changements locaux huitral"
+git push origin HEAD
+git fetch origin
+git checkout main
+git merge origin/main
+```
+Explication rapide :
+- `git status` : verifier l'etat local.
+- `git add -A` + `git commit` : sauvegarder les changements locaux pour ne rien perdre.
+- `git push origin HEAD` : publier ces changements sur chillka.
+- `git fetch origin` : recuperer les nouvelles refs.
+- `git checkout main` : se replacer sur la branche principale.
+- `git merge origin/main` : integrer la version centrale dans huitral.
+
+Option rapide (stocker temporairement) :
+```
+cd /var/www/lucien-sens-bon
+git status
+git stash push -m "wip huitral"
+git fetch origin
+git checkout main
+git merge origin/main
+git stash pop
+git add -A
+git commit -m "merge: main + wip huitral"
+git push origin main
+```
+Explication rapide :
+- `git stash push` : mettre les modifs de cote sans commit.
+- `git fetch` / `git checkout` / `git merge` : mettre a jour huitral.
+- `git stash pop` : remettre les changements au-dessus.
+- `git add -A` + `git commit` + `git push` : enregistrer et publier.
+
+### 11.3 Si vous voulez ecraser les changements locaux (attention)
+```
+cd /var/www/lucien-sens-bon
+git fetch origin
+git checkout main
+git reset --hard origin/main
+git clean -fd
+```
+Explication rapide :
+- `git reset --hard origin/main` : ecrase tout avec la version centrale.
+- `git clean -fd` : supprime les fichiers non suivis.
+
+Notes :
+- Ne pas committer `.env` (fichier local, secrets).
+- En cas de blocage, supprimer `.git/index.lock` avant de relancer Git.
+
|