From 807aef505023ba3aca5c86db0e4d7b6d22f7b0b0 Mon Sep 17 00:00:00 2001 From: toshiro Date: Sun, 25 Jan 2026 00:54:54 +0100 Subject: docs: update documentation --- .gitignore | 14 +- DOC_TECHNIQUE.md | 360 +++++++++++------------ app-management.md | 719 +++++++++++++++++++++++---------------------- storefront/public/.gitkeep | 2 +- 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 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 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 @@ - + -- cgit v1.2.3