From e704383cb20e7016794ccc793eda057a609be835 Mon Sep 17 00:00:00 2001 From: ertopogo Date: Sun, 1 Feb 2026 02:49:28 +0100 Subject: ajout de cart pour les commandes --- DOC_TECHNIQUE.md | 327 +++++++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 327 insertions(+) (limited to 'DOC_TECHNIQUE.md') 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 ` : 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 ""` : 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://:9000 +STORE_CORS=http://:8000 +``` + +2) Rebuild backend pour appliquer les variables : +``` +sudo docker compose up -d --build backend +``` + +3) Test CORS (storefront) : +``` +curl -i -H "Origin: http://:8000" http://: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. + -- cgit v1.2.3