path: root/DOC_TECHNIQUE.md

# 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.
- **Caddy** (sur araucaria) : reverse proxy + HTTPS automatique.

Ports principaux :
- `8000` : storefront (site public)
- `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/)
- [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/)
- [Caddy reverse proxy](https://caddyserver.com/docs/caddyfile/directives/reverse_proxy)

## 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.

### 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)

```
  Internet / LAN
        |
        v
  +---------------------------+
  |   araucaria (Caddy)       |
  |   HTTPS / reverse proxy   |
  |   lsb.arauco.online       |
  |   api-lsb.arauco.online   |
  +------------+--------------+
               |
               v
  +---------------------------+    huitral
  |                           |
  |  +--------------------+   |
  |  |   Storefront       |   |
  |  |   Next.js :8000    |   |
  |  +--------+-----------+   |
  |           |               |
  |           | HTTP (API)    |
  |           v               |
  |  +--------------------+   |
  |  |    MedusaJS        |   |
  |  |    :9000 (API)     |   |
  |  +-----+--------+----+   |
  |        |        |        |
  |   SQL  |        | Cache  |
  |        v        v        |
  |  +----------+ +-------+  |
  |  |PostgreSQL| | Redis |  |
  |  |  :5432   | | :6379 |  |
  |  +----------+ +-------+  |
  +---------------------------+
```

## 4. Installation rapide (serveur Linux)

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
```

### 4.1 Exemple reel (ce que nous avons fait)

Contexte : backend sur huitral:9000, storefront sur huitral:8000, Caddy sur araucaria.

1) Variables d'environnement (production) :
```
DATABASE_URL=postgres://luciensbdb:********@192.168.99.35:5432/sens_bon_db
JWT_SECRET=supersecret
COOKIE_SECRET=supersecret
NEXT_PUBLIC_MEDUSA_BACKEND_URL=https://api-lsb.arauco.online
ADMIN_CORS=https://api-lsb.arauco.online,https://lsb.arauco.online,http://api-lsb.huitral.ruka.lan,http://lsb.huitral.ruka.lan
STORE_CORS=https://lsb.arauco.online,http://lsb.huitral.ruka.lan
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) Import CSV produits :
```
sudo docker compose run --rm backend npm run import:products
```
Doc: `DOC_IMPORT_PRODUITS.md`

## 5. Tests rapides (serveur Linux)

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
```

### 5.1 Logs systeme avec journalctl (systemd)

Utiliser `journalctl` pour diagnostiquer les services systeme (Caddy, 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 <service>` : 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 "<date>"` : 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: https://lsb.arauco.online" https://api-lsb.arauco.online/store/products
```

- Confirme que `Access-Control-Allow-Origin` autorise le storefront.
- Pour le LAN : remplacer par `http://lsb.huitral.ruka.lan` et `http://api-lsb.huitral.ruka.lan`.

## 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 (serveur Linux)

### 7.1 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
```

### 7.2 Storefront affiche "Chargement des produits..."
Le storefront attend l'API backend. Verifier dans l'ordre :

1) `NEXT_PUBLIC_MEDUSA_BACKEND_URL` dans `.env` doit pointer vers l'API
   via Caddy (`https://api-lsb.arauco.online`), pas `localhost`.

2) Le backend repond sur `:9000` :
```
curl http://localhost:9000/store/products
```

3) Le storefront a ete **rebuild** apres changement de `.env`
   (`NEXT_PUBLIC_*` est injecte au build, pas au runtime) :
```
sudo docker compose up -d --build storefront
```

4) Les CORS sont corrects — `STORE_CORS` doit lister l'origine du storefront.
   Apres modification, recreer le conteneur (pas juste restart) :
```
sudo docker compose up -d backend
```

5) Le DNS LAN pointe vers **araucaria** (Caddy), pas vers huitral :
```
dig +short lsb.arauco.online
dig +short api-lsb.arauco.online
```
   Les deux doivent retourner l'IP d'araucaria. Si ca retourne l'IP de
   huitral, les navigateurs LAN contournent Caddy → `CONNECTION_REFUSED`
   sur le port 443. Corriger dans `/etc/dnsmasq.d/lsb.conf` sur araucaria.

### 7.3 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
```

### 7.4 CORS admin/storefront (procedure)

Objectif : autoriser le navigateur a appeler l'API depuis le storefront et l'admin.

1) Verifier `.env` :
```
NEXT_PUBLIC_MEDUSA_BACKEND_URL=https://api-lsb.arauco.online
ADMIN_CORS=https://api-lsb.arauco.online,https://lsb.arauco.online,http://api-lsb.huitral.ruka.lan,http://lsb.huitral.ruka.lan
STORE_CORS=https://lsb.arauco.online,http://lsb.huitral.ruka.lan
```

2) Rebuild backend pour appliquer les variables :
```
sudo docker compose up -d --build backend
```

3) Test CORS (storefront) :
```
curl -i -H "Origin: https://lsb.arauco.online" https://api-lsb.arauco.online/store/products
```

### 7.5 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
```

### 7.6 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 via Caddy sur araucaria)

Le reverse proxy est gere par **Caddy** sur `araucaria` (pas sur huitral).
Caddy gere automatiquement les certificats HTTPS via Let's Encrypt.

Configuration dans `/etc/caddy/Caddyfile` sur araucaria :
- `lsb.arauco.online` → huitral:8000 (storefront)
- `api-lsb.arauco.online` → huitral:9000 (backend)

Voir `INSTALLATION.md` section 5 pour le detail.

## 9. Sauvegarde et restauration (serveur Linux)

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.

## 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.

### 11.4 Comprendre les references Git (local vs distant)

Git stocke des pointeurs vers des commits. Ces pointeurs sont des references.

- Locales : `refs/heads/<branche>` (ex: `refs/heads/main`)
- Distantes : `refs/remotes/<remote>/<branche>` (ex: `refs/remotes/origin/main`)
- Tags : `refs/tags/<tag>`

Comment les voir :
```
git branch -a
```
Affiche les branches locales et distantes. Les distantes apparaissent sous `remotes/origin/...`.

```
git show-ref --heads
```
Liste les branches locales (refs/heads) et le commit pointe par chaque branche.

```
git show-ref --tags
```
Liste les tags (refs/tags). Si rien n'apparait, il n'y a pas de tags.

```
git show-ref --heads --tags --dereference
```
Affiche toutes les references et leurs commits. Utile si des tags pointent vers des objets annexes.

```
git show-ref --heads --quiet origin/main
```
Test silencieux : retourne un code de sortie 0 si la reference existe, 1 sinon.

Representation locale d'une branche distante :
- `origin/main` n'est pas une branche locale. C'est un **pointeur local** qui represente
  l'etat de la branche distante `main` a la date du dernier `git fetch`.
- Quand on fait `git fetch`, Git met a jour `refs/remotes/origin/main`.
- Quand on fait `git merge origin/main`, on integre cette reference distante dans la branche locale `main`.

### 11.5 Recuperer sur antel et nettoyer les fichiers .txt (poste Windows/WSL)

#### 11.5.1 Recuperer les mises a jour depuis chillka
Sur antel :
```
cd /mnt/e/Dev/Web-Works/Lucien-sens-bon
git fetch origin
git checkout main
git pull --ff-only
```
Explication rapide :
- `git fetch origin` : telecharge les refs distantes sans modifier la branche locale.
- `git checkout main` : se place sur la branche principale.
- `git pull --ff-only` : met a jour la branche locale **uniquement** si l'historique est lineaire.

Si antel a des changements locaux :
```
git status
git add -A
git commit -m "wip antel"
git pull --rebase
```
Explication rapide :
- `git commit` : sauvegarder les changements locaux.
- `git pull --rebase` : rejouer ces commits au-dessus de `origin/main` pour eviter un merge commit.

#### 11.5.2 Retirer des fichiers .txt deja stages
Si des fichiers .txt ne doivent pas etre versionnes :
```
git restore --staged _fichier-avec-erreurs/*.txt
rm -f _fichier-avec-erreurs/*.txt
```
Explication rapide :
- `git restore --staged` : retire les fichiers de l'index sans toucher le disque.
- `rm -f` : supprime les fichiers localement.

## 12. Commandes et diagnostics (annexe)

Cette annexe regroupe les commandes utilisees dans le projet, par theme, avec
les objectifs, parametres importants et alternatives utiles.  
Les commandes sont separees entre **serveur Linux** et **poste Windows/WSL**.

### 12.1 Serveur Linux

#### 12.1.1 Docker / Docker Compose (services Medusa + Storefront + Redis)

**Lancer les services**
```
docker compose up -d --build
```
- `docker compose` : plugin Compose integre (recommande).
- `up` : cree et demarre les services.
- `-d` : detache (retourne la main).
- `--build` : reconstruit les images si necessaire.
Alternatives :
- `docker-compose up -d --build` (ancienne syntaxe).
- `docker compose up` (sans `-d` : logs en direct).

**Voir l'etat des conteneurs**
```
docker compose ps
```
- aucun : liste services, statuts, ports.
Alternatives :
- `docker ps` (tous les conteneurs).
- `docker compose ps -a` (inclut les arretes).

**Voir les logs**
```
docker compose logs -f
docker compose logs -f backend
docker compose logs -f storefront
```
- `-f` : suivi temps reel (equivalent `tail -f`).
- `backend` / `storefront` : filtre par service.
Alternatives :
- `docker logs -f <container>`
- `docker compose logs --tail=200 backend`

**Redemarrer un service**
```
docker compose restart backend
```
- redemarre le service sans reconstruire l'image.
Alternatives :
- `docker compose up -d backend`
- `docker compose up -d --build backend`

**Rebuild force d'un service**
```
docker compose build --no-cache backend
docker compose up -d --build backend
```
- `--no-cache` : force l'installation des deps + postinstall.
- `--build` : rebuild puis redeploiement.
Alternatives :
- `docker compose build backend` (cache autorise).

**Entrer dans un conteneur**
```
docker exec -it medusa-backend sh
```
- `exec` : execute une commande dans un conteneur.
- `-it` : mode interactif + TTY.
- `sh` : shell minimal.
Alternatives :
- `docker exec -it medusa-backend bash` (si `bash` present).
- `docker compose exec backend sh`

**Commande dans un conteneur temporaire**
```
docker compose run --rm backend <commande>
```
- `run` : conteneur ponctuel base sur le service.
- `--rm` : supprime le conteneur a la fin.
Alternatives :
- `docker run --rm -it <image> <commande>`

#### 12.1.2 PostgreSQL (connexion, diagnostic, sauvegarde)

**Connexion via `DATABASE_URL`**
```
psql "$DATABASE_URL" -c "select 1;"
```
- `$DATABASE_URL` : `postgres://user:pass@host:5432/db`
- `-c` : execute une requete et quitte.
Alternatives :
- `psql -h <host> -U <user> -d <db> -W`
- `docker run --rm -it postgres:16-alpine psql "$DATABASE_URL" -c "select 1;"`

**Test du port reseau PostgreSQL**
```
nc -vz <host_db> 5432
```
- `-v` : verbose.
- `-z` : scan sans envoyer de donnees.
Alternatives :
- `telnet <host_db> 5432`
- `bash -c ">/dev/tcp/<host_db>/5432"` (si bash)

**Diagnostic hote (service / process)**
```
sudo systemctl status postgresql
sudo service postgresql status
ps aux | grep -E "postgres|postmaster"
```
- `systemctl` / `service` : verifie service systemd/sysv.
- `ps + grep` : liste les processus.
Alternatives :
- `pgrep -a postgres`
- `ss -lntp | grep 5432`

**Localiser la configuration**
```
sudo -u postgres psql -c "SHOW config_file;"
sudo -u postgres psql -c "SHOW hba_file;"
sudo -u postgres psql -c "SHOW data_directory;"
```
- donne les chemins exacts des fichiers de config et des donnees.
Alternatives (chemins typiques) :
- `/etc/postgresql/*/main/postgresql.conf`
- `/etc/postgresql/*/main/pg_hba.conf`
- `/var/lib/pgsql/data/postgresql.conf`
- `/var/lib/pgsql/data/pg_hba.conf`

**Commandes `psql` utiles (dans psql)**
```
\du
\l
\c ma_base
\dt
SHOW port;
SHOW listen_addresses;
```
- `\` : commandes internes psql.
- `SHOW ...` : variables de configuration.
Alternatives :
- `SELECT current_user;`
- `SELECT version();`

**Sauvegarde et restauration**
```
pg_dump -Fc -U user nom_db > /backups/lucien-sens-bon.dump
pg_restore -U user -d nom_db /backups/lucien-sens-bon.dump
```
- `-Fc` : format custom (compresse + restauration selective).
- `-U` : utilisateur.
Alternatives :
- `pg_dump -U user nom_db > dump.sql`
- `psql -U user -d nom_db < dump.sql`

#### 12.1.3 Medusa / Node.js (backend)

**Migrations Medusa**
```
docker compose run --rm backend npx medusa migrations run
```
- applique les migrations (creation des tables).
- `npx` : execute la version locale de Medusa.
Alternatives :
- `docker exec -it medusa-backend npx medusa migrations run`

**Seed de donnees**
```
docker compose run --rm backend npm run seed
```
- injecte des donnees demo si `backend/data/seed.json` existe.
Alternatives :
- `docker exec -it medusa-backend npm run seed`

**Import CSV produits**
```
docker compose run --rm backend npm run import:products
```
- importe les produits depuis `backend/data/products-import.csv` via `external_id`.
- doc: `DOC_IMPORT_PRODUITS.md`
Alternatives :
- `docker exec -it medusa-backend npm run import:products`

**Creation utilisateur admin (Medusa)**
```
docker exec -it medusa-backend medusa user -e admin@lucien.com -p supersecret
```
- `-e` : email de l'admin.
- `-p` : mot de passe.
Alternatives :
- `medusa user --help`

**Test DB via Node (diagnostic)**
```
docker compose run --rm backend node -e "const { Client }=require('pg'); ... "
```
- `node -e` : execute un script JS en ligne.
- `pg` : client PostgreSQL Node.
Alternatives :
- script JS temporaire dans le conteneur.
- `psql` direct (plus simple si acces).

#### 12.1.4 Storefront / Tests HTTP (curl)

**Test de l'API Medusa**
```
curl http://localhost:9000/store/products
```
- URL endpoint public Medusa.
Alternatives :
- `curl -v ...`
- `http :9000/store/products` (httpie)

**Test du storefront**
```
curl http://localhost:8000
```
- verifie que le site repond.
Alternatives :
- `curl -I http://localhost:8000`

**Test CORS**
```
curl -i -H "Origin: http://<IP>:8000" http://<IP>:9000/store/products
```
- `-i` : inclut les en-tetes.
- `-H` : ajoute un header `Origin`.
Alternatives :
- `curl -v ...`
- DevTools navigateur (onglet Network).

#### 12.1.5 Caddy / Reverse proxy (sur araucaria)

**Statut Caddy**
```
sudo systemctl status caddy
```

**Logs Caddy**
```
sudo journalctl -u caddy -f
sudo journalctl -u caddy -n 200 --no-pager
```
- `-f` : suivi temps reel.

**Editer le Caddyfile**
```
sudo nano /etc/caddy/Caddyfile
```

**Valider la config**
```
caddy validate --config /etc/caddy/Caddyfile
```

**Reload Caddy**
```
sudo systemctl reload caddy
```
- recharge la config sans couper les connexions actives.
Alternatives :
- `sudo systemctl restart caddy`
- `caddy reload --config /etc/caddy/Caddyfile`

#### 12.1.6 Systemd / Logs systeme (journalctl)

**Base**
```
sudo journalctl --disk-usage
sudo journalctl --list-boots
sudo journalctl -u <service> -n 50 --no-pager
sudo journalctl -u <service> -f
```
- `-u` : filtre par service.
- `-n` : n dernieres lignes.
- `-f` : suivi temps reel.
- `-b` : dernier boot.
- `-S` : depuis une date (ex: `10 min ago`).
- `--no-pager` : pas de pagination.

#### 12.1.7 Reseau / Ports (diagnostic)

**Ports locaux**
```
ss -lntp | egrep '8000|9000|5432|6379'
netstat -lntp | egrep '8000|9000|5432|6379'
```
- `ss` : outil moderne (remplace netstat).
- `-l` listening, `-n` numerique, `-t` TCP, `-p` process.
Alternatives :
- `lsof -iTCP -sTCP:LISTEN -n -P`

**Firewall**
```
sudo ufw status
```
Alternatives :
- `sudo iptables -S`
- `sudo firewall-cmd --list-all`

#### 12.1.8 Fichiers / Permissions

**Verifier presence d'un fichier**
```
ls -l docker-compose.yml
ls -l /etc/resolv.conf
```
- `-l` : details (droits, owner).
Alternatives :
- `stat <fichier>`

**Corriger les permissions du depot**
```
sudo chown -R "$USER":"$USER" /var/www/lucien-sens-bon
```
- redonne les droits a l'utilisateur courant.
Alternatives :
- `sudo chgrp -R <groupe> <dossier>`
- `sudo chmod -R g+w <dossier>`

#### 12.1.9 Git (workflow et maintenance)

**Etat et staging**
```
git status
git add -A
git reset HEAD .env output*.txt
```
- `add -A` : indexe ajouts + modifs + suppressions.
- `reset HEAD ...` : retire du staging sans toucher le disque.
Alternatives :
- `git add <fichier>`
- `git restore --staged <fichier>`

**Commit avec identite temporaire**
```
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"
```
- fixe l'identite uniquement pour cette commande.
Alternatives :
- `git -c user.name="..." -c user.email="..." commit -m "..."`

**Suivi de branche distante**
```
git branch --set-upstream-to=origin/docs-git-dns
```
- associe la branche locale a la branche distante.
Alternatives :
- `git push -u origin <branche>`

**Mise a jour sans merge commit**
```
git pull --rebase
git fetch origin
git pull --rebase origin docs-git-dns
```
- `rebase` : rejoue les commits locaux au-dessus de la remote.
Alternatives :
- `git pull --ff-only`

**Aligner strictement sur la remote (ATTENTION)**
```
git fetch origin
git reset --hard origin/main
git clean -fd
```
- ecrase les changements locaux + supprime les fichiers non suivis.
Alternatives :
- `git stash push -u -m "wip"`

**Stash pour rebase**
```
git stash push -u -m "wip avant rebase"
git stash pop
```
- sauvegarde temporaire des modifs non committes.
Alternatives :
- `git add -A` + `git commit` (si vous preferez un commit).

**References Git**
```
git branch -a
git show-ref --heads
git show-ref --tags
```
- affiche les branches locales, distantes et tags.

#### 12.1.10 Sauvegardes fichiers et depot

**Sauvegarder les uploads**
```
tar -czf /backups/medusa-uploads.tgz /var/www/lucien-sens-bon/backend/uploads
```
- `-c` : create, `-z` : gzip, `-f` : fichier output.
Alternatives :
- `rsync -a` (sauvegarde incrementale).

**Sauvegarder la config projet**
```
tar -czf /backups/lucien-sens-bon-config.tgz \
  /var/www/lucien-sens-bon/.env \
  /var/www/lucien-sens-bon/docker-compose.yml
```
- archive les fichiers critiques de config.

**Sauvegarder le depot Git (bare)**
```
git clone --mirror toshiro@chillka:/var/data/git/repositories/lucien-sens-bon.git \
  /backups/lucien-sens-bon.git
```
- `--mirror` : sauvegarde complete des refs/branches/tags.
Alternatives :
- `git bundle create backup.bundle --all`

#### 12.1.11 Edition / fichiers d'environnement

**Copier le modele `.env`**
```
cp env-example .env
```
- cree un fichier `.env` local avec les variables par defaut.
Alternatives :
- `cp -n env-example .env` (n'ecrase pas si `.env` existe).

**Editer un fichier**
```
vim .env
```
Alternatives :
- `nano .env`
- `code .env`

#### 12.1.12 Outils divers utiles

**Tests HTTP rapides (headers only)**
```
curl -I http://localhost:9000/store/products
```
- `-I` : en-tetes uniquement (plus rapide).
Alternatives :
- `wget --spider <url>`

**Recherche dans un conteneur**
```
docker compose run --rm backend sh -c "rg -n \"update\\(\\{\\},\" node_modules/@medusajs/medusa/dist/services"
```
- `rg -n` : recherche rapide avec numeros de lignes.
Alternatives :
- `grep -n <pattern> <fichier>`

### 12.2 Poste Windows (et WSL)

#### 12.2.1 DNS / Resolution (Windows + WSL)

**DNS local (Windows)**
```
nslookup www.lsb.huitral.ruka.lan
ipconfig /flushdns
```
Alternatives :
- `Resolve-DnsName` (PowerShell)

**DNS WSL**
```
dig +short www.lsb.huitral.ruka.lan
ls -l /etc/resolv.conf
sudo tee /etc/wsl.conf <<'EOF'
[network]
generateResolvConf = false
EOF
```
Alternatives :
- `nslookup`
- `host <nom>`