From 807aef505023ba3aca5c86db0e4d7b6d22f7b0b0 Mon Sep 17 00:00:00 2001 From: toshiro Date: Sun, 25 Jan 2026 00:54:54 +0100 Subject: docs: update documentation --- DOC_TECHNIQUE.md | 360 +++++++++++++++++++++++++++---------------------------- 1 file changed, 180 insertions(+), 180 deletions(-) (limited to 'DOC_TECHNIQUE.md') 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. + -- cgit v1.2.3