diff options
Diffstat (limited to 'DOC_TECHNIQUE.md')
| -rw-r--r-- | DOC_TECHNIQUE.md | 180 |
1 files changed, 180 insertions, 0 deletions
diff --git a/DOC_TECHNIQUE.md b/DOC_TECHNIQUE.md new file mode 100644 index 0000000..e8ec4e9 --- /dev/null +++ b/DOC_TECHNIQUE.md @@ -0,0 +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. + |