docs: update documentation

author: toshiro <toshiro@chillka> 2026-01-25 00:54:54 +0100
committer: toshiro <toshiro@chillka> 2026-01-25 00:54:54 +0100
commit: 807aef505023ba3aca5c86db0e4d7b6d22f7b0b0 (patch)
tree: 550326eeede559c7ccb19572969ff02ea7429cb3
parent: 92453cdf1ce1394b9010ac644b62615272f9fc43 (diff)
4 files changed, 562 insertions, 533 deletions
diff --git a/.gitignore b/.gitignore
index 1fc8fce..90f0d98 100644
--- a/.gitignore
+++ b/.gitignore
@@ -1,7 +1,7 @@
-backend-error-j.txt
-backend-error-k.txt
-backend-error-l.txt
-backend-error-m.txt
-backend-error-n.txt
-backend-error-o.txt
-backend-error-k_.txt
+backend-error-j.txt
+backend-error-k.txt
+backend-error-l.txt
+backend-error-m.txt
+backend-error-n.txt
+backend-error-o.txt
+backend-error-k_.txt
diff --git a/DOC_TECHNIQUE.md b/DOC_TECHNIQUE.md
index e8ec4e9..954cfb1 100644
--- a/DOC_TECHNIQUE.md
+++ b/DOC_TECHNIQUE.md
@@ -1,180 +1,180 @@
-# Documentation technique - Lucien-sens-bon
-
-Ce document explique l'architecture, les technologies, la mise en place, les tests
-et la sauvegarde/restauration du magasin en ligne. Il est ecrit pour une personne
-junior afin de pouvoir prendre en main le projet en autonomie.
-
-## 1) Vue d'ensemble
-
-Le projet est compose de :
-- **Backend MedusaJS** : API ecommerce (produits, panier, commandes).
-- **Storefront Next.js** : site web public.
-- **PostgreSQL** : base de donnees principale (clients, commandes, produits).
-- **Redis** : cache et event bus.
-- **Docker Compose** : orchestration des services.
-- **Apache** (optionnel) : reverse proxy pour publier en 80/443.
-
-Ports principaux :
-- `8000` : storefront (site public)
-- `9000` : backend (API + admin)
-- `6379` : redis
-
-## 2) Technologies utilisees (liens utiles)
-
-- MedusaJS : https://docs.medusajs.com/
-- Next.js : https://nextjs.org/docs
-- Docker : https://docs.docker.com/get-started/
-- Docker Compose : https://docs.docker.com/compose/
-- PostgreSQL : https://www.postgresql.org/docs/
-- Redis : https://redis.io/docs/latest/
-- Apache reverse proxy : https://httpd.apache.org/docs/2.4/howto/reverse_proxy.html
-
-## 3) Fichiers importants
-
-- `docker-compose.yml` : configuration des conteneurs.
-- `backend/` : code et config Medusa.
-- `storefront/` : code Next.js.
-- `.env` : variables d'environnement (non versionne).
-- `env-example` : modele de variables d'environnement.
-
-## 4) Installation rapide (serveur)
-
-1. Copier la configuration :
-```
-cp env-example .env
-```
-
-2. Completer `.env` (exemple) :
-```
-DATABASE_URL=postgres://user:password@host:5432/nom_db
-NEXT_PUBLIC_MEDUSA_BACKEND_URL=http://api.exemple.com
-ADMIN_CORS=http://api.exemple.com
-STORE_CORS=http://exemple.com
-JWT_SECRET=change_me
-COOKIE_SECRET=change_me
-```
-
-3. Lancer les services :
-```
-docker compose up -d --build
-```
-
-## 5) Tests rapides
-
-Verifier que les conteneurs tournent :
-```
-docker compose ps
-```
-
-Tester le storefront :
-```
-curl http://localhost:8000
-```
-
-Tester l'API Medusa :
-```
-curl http://localhost:9000/store/products
-```
-
-Voir les logs :
-```
-docker compose logs -f backend
-docker compose logs -f storefront
-```
-
-## 6) Ou se trouve la base de donnees ?
-
-Le backend lit la base de donnees via `DATABASE_URL` dans `.env`.
-Le format est :
-```
-postgres://user:password@host:5432/nom_db
-```
-
-Si PostgreSQL est externe au serveur, verifier l'ouverture du port `5432`
-et les autorisations reseau (pg_hba.conf cote PostgreSQL).
-
-## 7) Debogage courant
-
-### Backend qui redemarre en boucle
-Ca arrive si :
-- `DATABASE_URL` est incorrect
-- les migrations ne sont pas faites
-- le backend tente de compiler TypeScript sans dossier `src/`
-
-Commandes utiles :
-```
-docker compose logs -f backend
-docker exec -it medusa-backend npm run seed
-```
-
-### Storefront affiche "Chargement des produits..."
-Le storefront attend l'API backend. Verifier :
-- `NEXT_PUBLIC_MEDUSA_BACKEND_URL` dans `.env`
-- le backend repond sur `:9000`
-
-## 8) Mise en production (reverse proxy)
-
-Pour exposer en HTTP/HTTPS, utiliser Apache ou Nginx. Exemple Apache :
-- `apache-vhost.conf` dans le repo
-- activer `proxy` et `proxy_http`
-
-## 9) Sauvegarde et restauration
-
-Objectif : pouvoir recuperer **tout le site** et **l'historique**.
-Il faut sauvegarder :
-- la base PostgreSQL
-- les fichiers uploads (si utilises)
-- le fichier `.env`
-- le depot Git (historique du code)
-
-### 9.1 Sauvegarde PostgreSQL
-Sur le serveur de DB :
-```
-pg_dump -Fc -U user nom_db > /backups/lucien-sens-bon.dump
-```
-Doc officielle : https://www.postgresql.org/docs/current/app-pgdump.html
-
-### 9.2 Sauvegarde des uploads
-Si le backend stocke des fichiers :
-```
-tar -czf /backups/medusa-uploads.tgz /var/www/lucien-sens-bon/backend/uploads
-```
-
-### 9.3 Sauvegarde du depot Git
-Si le depot est sur un serveur Git (bare) :
-```
-git clone --mirror toshiro@chillka:/var/data/git/repositories/lucien-sens-bon.git /backups/lucien-sens-bon.git
-```
-
-### 9.4 Sauvegarde complete (exemple simple)
-```
-tar -czf /backups/lucien-sens-bon-config.tgz \
-  /var/www/lucien-sens-bon/.env \
-  /var/www/lucien-sens-bon/docker-compose.yml
-```
-
-### 9.5 Restauration rapide
-1) Restaurer la DB :
-```
-pg_restore -U user -d nom_db /backups/lucien-sens-bon.dump
-```
-Doc : https://www.postgresql.org/docs/current/app-pgrestore.html
-
-2) Restaurer les fichiers :
-```
-tar -xzf /backups/medusa-uploads.tgz -C /
-tar -xzf /backups/lucien-sens-bon-config.tgz -C /
-```
-
-3) Relancer les conteneurs :
-```
-docker compose up -d --build
-```
-
-## 10) Bonnes pratiques
-
-- Toujours versionner le code via Git (ne pas modifier uniquement sur serveur).
-- Sauvegarder la DB quotidiennement.
-- Garder un backup hors serveur (S3, autre machine).
-- Tester les restaurations une fois par trimestre.
-
+# Documentation technique - Lucien-sens-bon
+
+Ce document explique l'architecture, les technologies, la mise en place, les tests
+et la sauvegarde/restauration du magasin en ligne. Il est ecrit pour une personne
+junior afin de pouvoir prendre en main le projet en autonomie.
+
+## 1) Vue d'ensemble
+
+Le projet est compose de :
+- **Backend MedusaJS** : API ecommerce (produits, panier, commandes).
+- **Storefront Next.js** : site web public.
+- **PostgreSQL** : base de donnees principale (clients, commandes, produits).
+- **Redis** : cache et event bus.
+- **Docker Compose** : orchestration des services.
+- **Apache** (optionnel) : reverse proxy pour publier en 80/443.
+
+Ports principaux :
+- `8000` : storefront (site public)
+- `9000` : backend (API + admin)
+- `6379` : redis
+
+## 2) Technologies utilisees (liens utiles)
+
+- MedusaJS : https://docs.medusajs.com/
+- Next.js : https://nextjs.org/docs
+- Docker : https://docs.docker.com/get-started/
+- Docker Compose : https://docs.docker.com/compose/
+- PostgreSQL : https://www.postgresql.org/docs/
+- Redis : https://redis.io/docs/latest/
+- Apache reverse proxy : https://httpd.apache.org/docs/2.4/howto/reverse_proxy.html
+
+## 3) Fichiers importants
+
+- `docker-compose.yml` : configuration des conteneurs.
+- `backend/` : code et config Medusa.
+- `storefront/` : code Next.js.
+- `.env` : variables d'environnement (non versionne).
+- `env-example` : modele de variables d'environnement.
+
+## 4) Installation rapide (serveur)
+
+1. Copier la configuration :
+```
+cp env-example .env
+```
+
+2. Completer `.env` (exemple) :
+```
+DATABASE_URL=postgres://user:password@host:5432/nom_db
+NEXT_PUBLIC_MEDUSA_BACKEND_URL=http://api.exemple.com
+ADMIN_CORS=http://api.exemple.com
+STORE_CORS=http://exemple.com
+JWT_SECRET=change_me
+COOKIE_SECRET=change_me
+```
+
+3. Lancer les services :
+```
+docker compose up -d --build
+```
+
+## 5) Tests rapides
+
+Verifier que les conteneurs tournent :
+```
+docker compose ps
+```
+
+Tester le storefront :
+```
+curl http://localhost:8000
+```
+
+Tester l'API Medusa :
+```
+curl http://localhost:9000/store/products
+```
+
+Voir les logs :
+```
+docker compose logs -f backend
+docker compose logs -f storefront
+```
+
+## 6) Ou se trouve la base de donnees ?
+
+Le backend lit la base de donnees via `DATABASE_URL` dans `.env`.
+Le format est :
+```
+postgres://user:password@host:5432/nom_db
+```
+
+Si PostgreSQL est externe au serveur, verifier l'ouverture du port `5432`
+et les autorisations reseau (pg_hba.conf cote PostgreSQL).
+
+## 7) Debogage courant
+
+### Backend qui redemarre en boucle
+Ca arrive si :
+- `DATABASE_URL` est incorrect
+- les migrations ne sont pas faites
+- le backend tente de compiler TypeScript sans dossier `src/`
+
+Commandes utiles :
+```
+docker compose logs -f backend
+docker exec -it medusa-backend npm run seed
+```
+
+### Storefront affiche "Chargement des produits..."
+Le storefront attend l'API backend. Verifier :
+- `NEXT_PUBLIC_MEDUSA_BACKEND_URL` dans `.env`
+- le backend repond sur `:9000`
+
+## 8) Mise en production (reverse proxy)
+
+Pour exposer en HTTP/HTTPS, utiliser Apache ou Nginx. Exemple Apache :
+- `apache-vhost.conf` dans le repo
+- activer `proxy` et `proxy_http`
+
+## 9) Sauvegarde et restauration
+
+Objectif : pouvoir recuperer **tout le site** et **l'historique**.
+Il faut sauvegarder :
+- la base PostgreSQL
+- les fichiers uploads (si utilises)
+- le fichier `.env`
+- le depot Git (historique du code)
+
+### 9.1 Sauvegarde PostgreSQL
+Sur le serveur de DB :
+```
+pg_dump -Fc -U user nom_db > /backups/lucien-sens-bon.dump
+```
+Doc officielle : https://www.postgresql.org/docs/current/app-pgdump.html
+
+### 9.2 Sauvegarde des uploads
+Si le backend stocke des fichiers :
+```
+tar -czf /backups/medusa-uploads.tgz /var/www/lucien-sens-bon/backend/uploads
+```
+
+### 9.3 Sauvegarde du depot Git
+Si le depot est sur un serveur Git (bare) :
+```
+git clone --mirror toshiro@chillka:/var/data/git/repositories/lucien-sens-bon.git /backups/lucien-sens-bon.git
+```
+
+### 9.4 Sauvegarde complete (exemple simple)
+```
+tar -czf /backups/lucien-sens-bon-config.tgz \
+  /var/www/lucien-sens-bon/.env \
+  /var/www/lucien-sens-bon/docker-compose.yml
+```
+
+### 9.5 Restauration rapide
+1) Restaurer la DB :
+```
+pg_restore -U user -d nom_db /backups/lucien-sens-bon.dump
+```
+Doc : https://www.postgresql.org/docs/current/app-pgrestore.html
+
+2) Restaurer les fichiers :
+```
+tar -xzf /backups/medusa-uploads.tgz -C /
+tar -xzf /backups/lucien-sens-bon-config.tgz -C /
+```
+
+3) Relancer les conteneurs :
+```
+docker compose up -d --build
+```
+
+## 10) Bonnes pratiques
+
+- Toujours versionner le code via Git (ne pas modifier uniquement sur serveur).
+- Sauvegarder la DB quotidiennement.
+- Garder un backup hors serveur (S3, autre machine).
+- Tester les restaurations une fois par trimestre.
+
diff --git a/app-management.md b/app-management.md
index b507648..20c5f5c 100644
--- a/app-management.md
+++ b/app-management.md
@@ -1,345 +1,374 @@
-# App management - Lucien-sens-bon
-
-Ce document explique comment diagnostiquer les conteneurs, la base de donnees
-et le reverse proxy (Apache).
-
-## 1) Diagnostic Docker
-
-Statut des services :
-```
-docker compose ps
-```
-
-Logs temps reel :
-```
-docker compose logs -f
-docker compose logs -f backend
-docker compose logs -f storefront
-```
-
-Redemarrer un service :
-```
-docker compose restart backend
-```
-
-Rebuild force d'un service :
-```
-docker compose build --no-cache backend
-docker compose up -d --build backend
-```
-
-Entrer dans un conteneur :
-```
-docker exec -it medusa-backend sh
-```
-
-## 2) Verifier la connexion PostgreSQL
-
-La connexion est definie dans `.env` :
-```
-DATABASE_URL=postgres://user:password@host:5432/nom_db
-```
-
-### 2.1 Tester depuis le serveur (si psql est installe)
-```
-psql "$DATABASE_URL" -c "select 1;"
-```
-
-### 2.2 Tester depuis un conteneur temporaire
-```
-docker run --rm -it postgres:16-alpine psql "$DATABASE_URL" -c "select 1;"
-```
-
-### 2.3 Tester le port (reseau)
-```
-nc -vz <host_db> 5432
-```
-
-Si la DB est sur la machine hote :
-- eviter `localhost` dans `DATABASE_URL`
-- utiliser l'IP de la machine hote
-
-Documentation PostgreSQL :
-https://www.postgresql.org/docs/current/app-psql.html
-https://www.postgresql.org/docs/current/app-pg-isready.html
-
-## 3) Tests applicatifs rapides
-
-Storefront :
-```
-curl http://localhost:8000
-```
-
-API Medusa :
-```
-curl http://localhost:9000/store/products
-```
-
-## 3.1) Depannage avance: backend 9000 ne repond pas
-
-Cette section documente les commandes utilisees en incident et explique
-ce qu'elles permettent de verifier.
-
-### A) Etre dans le bon dossier compose
-
-```
-cd /var/www/lucien-sens-bon
-ls -l docker-compose.yml
-```
-
-- `cd ...` : se place dans le dossier ou se trouve `docker-compose.yml`.
-- `ls -l docker-compose.yml` : confirme que le fichier compose existe
-  (sinon `docker compose` renvoie "no configuration file provided").
-
-### B) Etat et logs du backend
-
-```
-sudo docker compose ps
-sudo docker compose logs -f backend
-```
-
-- `docker compose ps` : liste les conteneurs, leur statut et les ports publies.
-- `docker compose logs -f backend` : suit les logs du backend en temps reel
-  pour identifier l'erreur exacte.
-
-### C) Test HTTP local (depuis le serveur)
-
-```
-curl -v http://localhost:9000/store/products
-```
-
-- `curl -v` : verifie que l'API repond et montre les details de connexion.
-- Si "connection reset by peer" -> le backend crash apres accept.
-
-### D) Verifier la base (depuis un conteneur temporaire)
-
-```
-sudo docker compose run --rm backend node -e "const { Client }=require('pg'); const c=new Client({connectionString: process.env.DATABASE_URL}); c.connect().then(()=>console.log('DB OK')).catch(e=>{console.error('DB ERROR:', e.message); process.exit(1)})"
-```
-
-- `docker compose run --rm backend` : lance un conteneur temporaire base sur
-  l'image backend (meme environnement que le service).
-- `node -e ...` : teste la connexion a PostgreSQL via `DATABASE_URL`.
-
-### E) Tester droits et extension PostgreSQL
-
-```
-sudo docker compose run --rm backend node -e "const {Client}=require('pg'); const c=new Client({connectionString: process.env.DATABASE_URL}); c.connect().then(async()=>{const p=await c.query(\"select has_database_privilege(current_user, current_database(), 'CREATE') as can_create\"); console.log(p.rows); try{await c.query('CREATE EXTENSION IF NOT EXISTS \"uuid-ossp\"'); console.log('EXT OK');}catch(e){console.error('EXT ERROR:', e.message);} await c.end();}).catch(e=>{console.error('DB ERROR:', e.message); process.exit(1);});"
-```
-
-- Verifie que l'utilisateur a le droit de creer dans la base.
-- Cree l'extension `uuid-ossp` si elle manque (souvent requise par Medusa).
-
-### F) Migrations Medusa (creation des tables)
-
-```
-sudo docker compose run --rm backend npx medusa migrations run
-```
-
-- Applique les migrations en base. Sans ca, le backend peut echouer a demarrer.
-
-### G) Seed de donnees (optionnel)
-
-```
-sudo docker compose run --rm backend npm run seed
-```
-
-- Ajoute des donnees de demo si un fichier seed existe.
-- Si le fichier `data/seed.json` manque, cette commande echoue sans impact
-  sur le demarrage de l'API.
-
-### H) Redemarrage et rebuild
-
-```
-sudo docker compose restart backend
-sudo docker compose up -d --build backend
-```
-
-- `restart` : redemarre seulement le backend.
-- `up -d --build` : reconstruit l'image puis redemarre le service.
-
-### I) Cas erreur PaymentProviderService (crash apres init)
-
-```
-sudo docker compose run --rm backend node -e "const {Client}=require('pg'); const c=new Client({connectionString: process.env.DATABASE_URL}); c.connect().then(async()=>{const rows=await c.query('select * from payment_provider'); console.log(rows.rows); await c.end();}).catch(e=>{console.error('DB ERROR:', e.message); process.exit(1);});"
-```
-
-- Controle le contenu de `payment_provider` si le backend plante au demarrage
-  dans le service des providers de paiement.
-
-## 4) Apache / Reverse proxy
-
-Verifier les services Apache :
-```
-sudo systemctl status apache2
-```
-
-Logs Apache :
-```
-sudo journalctl -u apache2 -f
-sudo tail -f /var/log/apache2/error.log
-sudo tail -f /var/log/apache2/access.log
-```
-
-Modules proxy :
-```
-sudo a2enmod proxy
-sudo a2enmod proxy_http
-```
-
-Reload Apache :
-```
-sudo systemctl reload apache2
-```
-
-Documentation Apache reverse proxy :
-https://httpd.apache.org/docs/2.4/howto/reverse_proxy.html
-
-## 5) Ports a verifier
-
-- `8000` : storefront
-- `9000` : backend
-- `5432` : PostgreSQL
-- `6379` : Redis
-
-Verifier l'ouverture locale :
-```
-ss -lntp | egrep '8000|9000|5432|6379'
-```
-
-Verifier le firewall (UFW) :
-```
-sudo ufw status
-```
-
-## 6) Git - Remise en ordre apres modifications locales
-
-Cette section documente les commandes utilisees pour remettre la branche locale
-en etat propre, definir le suivi distant, et pousser les changements.
-
-### A) Retirer les fichiers sensibles ou locaux du commit
-
-```
-git reset HEAD .env output*.txt
-```
-
-- Retire `.env` et les fichiers `output*.txt` du staging.
-- Evite d'inclure des secrets ou des artefacts locaux dans le commit.
-
-### B) Corriger les droits si `.git` est en lecture seule
-
-```
-sudo chown -R "$USER":"$USER" /var/www/lucien-sens-bon
-```
-
-- Redonne les droits d'ecriture a l'utilisateur courant sur le depot.
-- Corrige l'erreur `Permission denied` lors de la creation du commit.
-
-### C) Committer en definissant l'identite temporairement
-
-```
-GIT_AUTHOR_NAME="toshiro" GIT_AUTHOR_EMAIL="toshiro@chillka" GIT_COMMITTER_NAME="toshiro" GIT_COMMITTER_EMAIL="toshiro@chillka" git commit -m "local changes on huitral"
-```
-
-- Injecte l'identite uniquement pour ce commit, sans modifier la configuration
-  globale de git.
-- Permet de valider le commit quand `user.name`/`user.email` ne sont pas definis.
-
-### D) Definir la branche distante suivie
-
-```
-git branch --set-upstream-to=origin/docs-git-dns
-```
-
-- Associe `docs-git-dns` a la branche distante pour autoriser `git pull`.
-
-### E) Rebaser sur la remote puis pousser
-
-```
-git pull --rebase
-git push origin docs-git-dns
-```
-
-- `pull --rebase` aligne la branche locale sur la remote sans commit de merge.
-- `push` publie les commits locaux sur la remote.
-
-### F) Recuperer le dernier code sur un serveur (alignement strict)
-
-```
-cd /var/www/lucien-sens-bon
-git fetch origin
-git checkout docs-git-dns
-git reset --hard origin/docs-git-dns
-```
-
-- S'assure d'etre a la racine du depot (pas dans `backend/`).
-- Aligne la branche locale strictement sur la remote (`origin/docs-git-dns`).
-- Ecrase les changements locaux sur cette branche.
-
-Verifier la presence d'un fichier sur la remote :
-```
-git ls-tree -r origin/docs-git-dns --name-only | grep "backend/scripts/patch-medusa.js"
-```
-
-- Confirme que le fichier existe bien sur la branche distante.
-
-Nettoyer les fichiers non suivis (optionnel) :
-```
-git clean -fd
-```
-
-- Supprime les fichiers/dossiers non suivis (ex: `output*.txt`, `uploads/`).
-
-### G) Push refuse (non-fast-forward) + rebase avec identite temporaire
-
-Si `git push` refuse avec `non-fast-forward`, integrer la remote puis repousser.
-
-1) Mettre de cote les fichiers locaux non committes :
-```
-git status
-git stash push -u -m "wip avant rebase"
-```
-
-2) Rebaser avec identite temporaire (sans modifier la config git) :
-```
-git -c user.name="toshiro" -c user.email="toshiro@chillka" pull --rebase origin docs-git-dns
-```
-
-3) Si un rebase est en cours et demande un commit :
-```
-git -c user.name="toshiro" -c user.email="toshiro@chillka" commit -m "local changes on huitral"
-git -c user.name="toshiro" -c user.email="toshiro@chillka" rebase --continue
-```
-
-4) Pousser puis restaurer le stash :
-```
-git push origin docs-git-dns
-git stash pop
-```
-
-- Le rebase rejoue les commits locaux au-dessus de la remote.
-- L'option `-c user.name/user.email` injecte l'identite uniquement pour la commande.
-
-### H) Ignorer les fichiers locaux (.env, output*.txt)
-
-Option 1 - Ignorer pour tout le depot (partage en equipe) :
-```
-# .gitignore (exemples)
-.env
-output*.txt
-```
-
-- Ajoute ces patterns au `.gitignore` si ces fichiers ne doivent jamais etre commits.
-- Utile pour les fichiers generes localement.
-
-Option 2 - Ignorer localement sans toucher au `.gitignore` :
-```
-git update-index --skip-worktree .env
-```
-
-- Masque les changements locaux de `.env` sans impacter le depot distant.
-- Annuler si besoin :
-```
-git update-index --no-skip-worktree .env
-```
-
+# App management - Lucien-sens-bon
+
+Ce document explique comment diagnostiquer les conteneurs, la base de donnees
+et le reverse proxy (Apache).
+
+## 1) Diagnostic Docker
+
+Statut des services :
+```
+docker compose ps
+```
+
+Logs temps reel :
+```
+docker compose logs -f
+docker compose logs -f backend
+docker compose logs -f storefront
+```
+
+Redemarrer un service :
+```
+docker compose restart backend
+```
+
+Rebuild force d'un service :
+```
+docker compose build --no-cache backend
+docker compose up -d --build backend
+```
+
+Entrer dans un conteneur :
+```
+docker exec -it medusa-backend sh
+```
+
+## 2) Verifier la connexion PostgreSQL
+
+La connexion est definie dans `.env` :
+```
+DATABASE_URL=postgres://user:password@host:5432/nom_db
+```
+
+### 2.1 Tester depuis le serveur (si psql est installe)
+```
+psql "$DATABASE_URL" -c "select 1;"
+```
+
+### 2.2 Tester depuis un conteneur temporaire
+```
+docker run --rm -it postgres:16-alpine psql "$DATABASE_URL" -c "select 1;"
+```
+
+### 2.3 Tester le port (reseau)
+```
+nc -vz <host_db> 5432
+```
+
+Si la DB est sur la machine hote :
+- eviter `localhost` dans `DATABASE_URL`
+- utiliser l'IP de la machine hote
+
+Documentation PostgreSQL :
+https://www.postgresql.org/docs/current/app-psql.html
+https://www.postgresql.org/docs/current/app-pg-isready.html
+
+## 3) Tests applicatifs rapides
+
+Storefront :
+```
+curl http://localhost:8000
+```
+
+API Medusa :
+```
+curl http://localhost:9000/store/products
+```
+
+## 3.1) Depannage avance: backend 9000 ne repond pas
+
+Cette section documente les commandes utilisees en incident et explique
+ce qu'elles permettent de verifier.
+
+### A) Etre dans le bon dossier compose
+
+```
+cd /var/www/lucien-sens-bon
+ls -l docker-compose.yml
+```
+
+- `cd ...` : se place dans le dossier ou se trouve `docker-compose.yml`.
+- `ls -l docker-compose.yml` : confirme que le fichier compose existe
+  (sinon `docker compose` renvoie "no configuration file provided").
+
+### B) Etat et logs du backend
+
+```
+sudo docker compose ps
+sudo docker compose logs -f backend
+```
+
+- `docker compose ps` : liste les conteneurs, leur statut et les ports publies.
+- `docker compose logs -f backend` : suit les logs du backend en temps reel
+  pour identifier l'erreur exacte.
+
+### C) Test HTTP local (depuis le serveur)
+
+```
+curl -v http://localhost:9000/store/products
+```
+
+- `curl -v` : verifie que l'API repond et montre les details de connexion.
+- Si "connection reset by peer" -> le backend crash apres accept.
+
+### D) Verifier la base (depuis un conteneur temporaire)
+
+```
+sudo docker compose run --rm backend node -e "const { Client }=require('pg'); const c=new Client({connectionString: process.env.DATABASE_URL}); c.connect().then(()=>console.log('DB OK')).catch(e=>{console.error('DB ERROR:', e.message); process.exit(1)})"
+```
+
+- `docker compose run --rm backend` : lance un conteneur temporaire base sur
+  l'image backend (meme environnement que le service).
+- `node -e ...` : teste la connexion a PostgreSQL via `DATABASE_URL`.
+
+### E) Tester droits et extension PostgreSQL
+
+```
+sudo docker compose run --rm backend node -e "const {Client}=require('pg'); const c=new Client({connectionString: process.env.DATABASE_URL}); c.connect().then(async()=>{const p=await c.query(\"select has_database_privilege(current_user, current_database(), 'CREATE') as can_create\"); console.log(p.rows); try{await c.query('CREATE EXTENSION IF NOT EXISTS \"uuid-ossp\"'); console.log('EXT OK');}catch(e){console.error('EXT ERROR:', e.message);} await c.end();}).catch(e=>{console.error('DB ERROR:', e.message); process.exit(1);});"
+```
+
+- Verifie que l'utilisateur a le droit de creer dans la base.
+- Cree l'extension `uuid-ossp` si elle manque (souvent requise par Medusa).
+
+### F) Migrations Medusa (creation des tables)
+
+```
+sudo docker compose run --rm backend npx medusa migrations run
+```
+
+- Applique les migrations en base. Sans ca, le backend peut echouer a demarrer.
+
+### G) Seed de donnees (optionnel)
+
+```
+sudo docker compose run --rm backend npm run seed
+```
+
+- Ajoute des donnees de demo si un fichier seed existe.
+- Si le fichier `data/seed.json` manque, cette commande echoue sans impact
+  sur le demarrage de l'API.
+
+### H) Redemarrage et rebuild
+
+```
+sudo docker compose restart backend
+sudo docker compose up -d --build backend
+```
+
+- `restart` : redemarre seulement le backend.
+- `up -d --build` : reconstruit l'image puis redemarre le service.
+
+### I) Cas erreur PaymentProviderService (crash apres init)
+
+```
+sudo docker compose run --rm backend node -e "const {Client}=require('pg'); const c=new Client({connectionString: process.env.DATABASE_URL}); c.connect().then(async()=>{const rows=await c.query('select * from payment_provider'); console.log(rows.rows); await c.end();}).catch(e=>{console.error('DB ERROR:', e.message); process.exit(1);});"
+```
+
+- Controle le contenu de `payment_provider` si le backend plante au demarrage
+  dans le service des providers de paiement.
+
+## 4) Apache / Reverse proxy
+
+Verifier les services Apache :
+```
+sudo systemctl status apache2
+```
+
+Logs Apache :
+```
+sudo journalctl -u apache2 -f
+sudo tail -f /var/log/apache2/error.log
+sudo tail -f /var/log/apache2/access.log
+```
+
+Modules proxy :
+```
+sudo a2enmod proxy
+sudo a2enmod proxy_http
+```
+
+Reload Apache :
+```
+sudo systemctl reload apache2
+```
+
+Documentation Apache reverse proxy :
+https://httpd.apache.org/docs/2.4/howto/reverse_proxy.html
+
+## 5) Ports a verifier
+
+- `8000` : storefront
+- `9000` : backend
+- `5432` : PostgreSQL
+- `6379` : Redis
+
+Verifier l'ouverture locale :
+```
+ss -lntp | egrep '8000|9000|5432|6379'
+```
+
+Verifier le firewall (UFW) :
+```
+sudo ufw status
+```
+
+## 6) Git - Remise en ordre apres modifications locales
+
+Cette section documente les commandes utilisees pour remettre la branche locale
+en etat propre, definir le suivi distant, et pousser les changements.
+
+### A) Retirer les fichiers sensibles ou locaux du commit
+
+```
+git reset HEAD .env output*.txt
+```
+
+- Retire `.env` et les fichiers `output*.txt` du staging.
+- Evite d'inclure des secrets ou des artefacts locaux dans le commit.
+
+### B) Corriger les droits si `.git` est en lecture seule
+
+```
+sudo chown -R "$USER":"$USER" /var/www/lucien-sens-bon
+```
+
+- Redonne les droits d'ecriture a l'utilisateur courant sur le depot.
+- Corrige l'erreur `Permission denied` lors de la creation du commit.
+
+### C) Committer en definissant l'identite temporairement
+
+```
+GIT_AUTHOR_NAME="toshiro" GIT_AUTHOR_EMAIL="toshiro@chillka" GIT_COMMITTER_NAME="toshiro" GIT_COMMITTER_EMAIL="toshiro@chillka" git commit -m "local changes on huitral"
+```
+
+- Injecte l'identite uniquement pour ce commit, sans modifier la configuration
+  globale de git.
+- Permet de valider le commit quand `user.name`/`user.email` ne sont pas definis.
+
+### D) Definir la branche distante suivie
+
+```
+git branch --set-upstream-to=origin/docs-git-dns
+```
+
+- Associe `docs-git-dns` a la branche distante pour autoriser `git pull`.
+
+### E) Rebaser sur la remote puis pousser
+
+```
+git pull --rebase
+git push origin docs-git-dns
+```
+
+- `pull --rebase` aligne la branche locale sur la remote sans commit de merge.
+- `push` publie les commits locaux sur la remote.
+
+### F) Recuperer le dernier code sur un serveur (alignement strict)
+
+```
+cd /var/www/lucien-sens-bon
+git fetch origin
+git checkout docs-git-dns
+git reset --hard origin/docs-git-dns
+```
+
+- S'assure d'etre a la racine du depot (pas dans `backend/`).
+- Aligne la branche locale strictement sur la remote (`origin/docs-git-dns`).
+- Ecrase les changements locaux sur cette branche.
+
+Verifier la presence d'un fichier sur la remote :
+```
+git ls-tree -r origin/docs-git-dns --name-only | grep "backend/scripts/patch-medusa.js"
+```
+
+- Confirme que le fichier existe bien sur la branche distante.
+
+Nettoyer les fichiers non suivis (optionnel) :
+```
+git clean -fd
+```
+
+- Supprime les fichiers/dossiers non suivis (ex: `output*.txt`, `uploads/`).
+
+### G) Push refuse (non-fast-forward) + rebase avec identite temporaire
+
+Si `git push` refuse avec `non-fast-forward`, integrer la remote puis repousser.
+
+1) Mettre de cote les fichiers locaux non committes :
+```
+git status
+git stash push -u -m "wip avant rebase"
+```
+
+2) Rebaser avec identite temporaire (sans modifier la config git) :
+```
+git -c user.name="toshiro" -c user.email="toshiro@chillka" pull --rebase origin docs-git-dns
+```
+
+3) Si un rebase est en cours et demande un commit :
+```
+git -c user.name="toshiro" -c user.email="toshiro@chillka" commit -m "local changes on huitral"
+git -c user.name="toshiro" -c user.email="toshiro@chillka" rebase --continue
+```
+
+4) Pousser puis restaurer le stash :
+```
+git push origin docs-git-dns
+git stash pop
+```
+
+- Le rebase rejoue les commits locaux au-dessus de la remote.
+- L'option `-c user.name/user.email` injecte l'identite uniquement pour la commande.
+
+### H) Ignorer les fichiers locaux (.env, output*.txt)
+
+Option 1 - Ignorer pour tout le depot (partage en equipe) :
+```
+# .gitignore (exemples)
+.env
+output*.txt
+```
+
+- Ajoute ces patterns au `.gitignore` si ces fichiers ne doivent jamais etre commits.
+- Utile pour les fichiers generes localement.
+
+Option 2 - Ignorer localement sans toucher au `.gitignore` :
+```
+git update-index --skip-worktree .env
+```
+
+- Masque les changements locaux de `.env` sans impacter le depot distant.
+- Annuler si besoin :
+```
+git update-index --no-skip-worktree .env
+```
+
+### I) Pull refuse (divergent branches) sans modifier la config
+
+Probleme :
+```
+fatal: Need to specify how to reconcile divergent branches.
+```
+
+Cause :
+- La branche locale et la branche distante ont diverge.
+- Git demande une strategie explicite (merge, rebase, ff-only).
+
+Solution recommandee (rebase ponctuel) :
+```
+git fetch origin
+git pull --rebase origin docs-git-dns
+git push origin docs-git-dns
+```
+
+- `--rebase` aligne l'historique local sans commit de merge.
+- A utiliser sans changer `git config`, juste pour cette commande.
+
+Si des changements locaux non committes existent :
+```
+git stash push -u -m "wip avant rebase"
+git pull --rebase origin docs-git-dns
+git push origin docs-git-dns
+git stash pop
+```
+
diff --git a/storefront/public/.gitkeep b/storefront/public/.gitkeep
index 8d1c8b6..56f3b36 100644
--- a/storefront/public/.gitkeep
+++ b/storefront/public/.gitkeep
@@ -1 +1 @@
- 
+
author	toshiro <toshiro@chillka>	2026-01-25 00:54:54 +0100
committer	toshiro <toshiro@chillka>	2026-01-25 00:54:54 +0100
commit	807aef505023ba3aca5c86db0e4d7b6d22f7b0b0 (patch)
tree	550326eeede559c7ccb19572969ff02ea7429cb3
parent	92453cdf1ce1394b9010ac644b62615272f9fc43 (diff)