path: root/helper-cmd.md

# Helper - Commandes du projet Lucien-sens-bon

Ce document explique les commandes utilisées dans ce projet, classées par thème.  
Pour chaque commande : objectif, paramètres importants, et alternatives utiles.

## 1. Docker / Docker Compose (services Medusa + Storefront + Redis)

### 1.1 Lancer les services
**Commande**
```
docker compose up -d --build
```
**Explication**
- `docker compose` : plugin Compose intégré (recommandé).
- `up` : crée et démarre les services.
- `-d` : détaché (retourne la main).
- `--build` : reconstruit les images si nécessaire.

**Alternatives**
- `docker-compose up -d --build` (ancienne syntaxe).
- `docker compose up` (sans `-d` : logs en direct).

### 1.2 Voir l'état des conteneurs
**Commande**
```
docker compose ps
```
**Paramètres**
- aucun : liste services, statuts, ports.

**Alternatives**
- `docker ps` : tous les conteneurs (tous projets).
- `docker compose ps -a` : inclut les conteneurs arrêtés.

### 1.3 Voir les logs
**Commande**
```
docker compose logs -f
docker compose logs -f backend
docker compose logs -f storefront
```
**Paramètres**
- `-f` : suivi temps réel (équivalent `tail -f`).
- `backend` / `storefront` : filtre par service.

**Alternatives**
- `docker logs -f <container>`
- `docker compose logs --tail=200 backend`

### 1.4 Redémarrer un service
**Commande**
```
docker compose restart backend
```
**Explication**
- redémarre le service sans reconstruire l’image.

**Alternatives**
- `docker compose up -d backend`
- `docker compose up -d --build backend`

### 1.5 Rebuild forcé d’un service
**Commande**
```
docker compose build --no-cache backend
docker compose up -d --build backend
```
**Paramètres**
- `--no-cache` : force l’installation des deps + postinstall.
- `--build` : rebuild puis redeploiement.

**Alternatives**
- `docker compose build backend` (cache autorisé).

### 1.6 Entrer dans un conteneur
**Commande**
```
docker exec -it medusa-backend sh
```
**Paramètres**
- `exec` : exécute une commande dans un conteneur.
- `-it` : mode interactif + TTY.
- `sh` : shell minimal.

**Alternatives**
- `docker exec -it medusa-backend bash` (si `bash` présent).
- `docker compose exec backend sh`

### 1.7 Commande dans un conteneur temporaire
**Commande**
```
docker compose run --rm backend <commande>
```
**Paramètres**
- `run` : conteneur ponctuel basé sur le service.
- `--rm` : supprime le conteneur à la fin.

**Alternatives**
- `docker run --rm -it <image> <commande>`

## 2. PostgreSQL (connexion, diagnostic, sauvegarde)

### 2.1 Connexion via `DATABASE_URL`
**Commande**
```
psql "$DATABASE_URL" -c "select 1;"
```
**Paramètres**
- `$DATABASE_URL` : `postgres://user:pass@host:5432/db`
- `-c` : exécute une requête et quitte.

**Alternatives**
- `psql -h <host> -U <user> -d <db> -W`
- `docker run --rm -it postgres:16-alpine psql "$DATABASE_URL" -c "select 1;"`

### 2.2 Test du port réseau PostgreSQL
**Commande**
```
nc -vz <host_db> 5432
```
**Paramètres**
- `-v` : verbose.
- `-z` : scan sans envoyer de données.

**Alternatives**
- `telnet <host_db> 5432`
- `bash -c ">/dev/tcp/<host_db>/5432"` (si bash)

### 2.3 Diagnostic hôte (service / process)
**Commandes**
```
sudo systemctl status postgresql
sudo service postgresql status
ps aux | grep -E "postgres|postmaster"
```
**Paramètres**
- `systemctl` / `service` : vérifie service systemd/sysv.
- `ps + grep` : liste les processus.

**Alternatives**
- `pgrep -a postgres`
- `ss -lntp | grep 5432`

### 2.4 Localiser la configuration
**Commandes**
```
sudo -u postgres psql -c "SHOW config_file;"
sudo -u postgres psql -c "SHOW hba_file;"
sudo -u postgres psql -c "SHOW data_directory;"
```
**Explication**
- donne les chemins exacts des fichiers de config et des données.

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

### 2.5 Commandes `psql` utiles (dans psql)
**Commandes**
```
\du
\l
\c ma_base
\dt
SHOW port;
SHOW listen_addresses;
```
**Paramètres**
- `\` : commandes internes psql.
- `SHOW ...` : variables de configuration.

**Alternatives**
- `SELECT current_user;`
- `SELECT version();`

### 2.6 Sauvegarde et restauration
**Commandes**
```
pg_dump -Fc -U user nom_db > /backups/lucien-sens-bon.dump
pg_restore -U user -d nom_db /backups/lucien-sens-bon.dump
```
**Paramètres**
- `-Fc` : format custom (compressé + restauration sélective).
- `-U` : utilisateur.

**Alternatives**
- `pg_dump -U user nom_db > dump.sql`
- `psql -U user -d nom_db < dump.sql`

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

### 3.1 Migrations Medusa
**Commande**
```
docker compose run --rm backend npx medusa migrations run
```
**Explication**
- applique les migrations (création des tables).

**Paramètres**
- `npx` : exécute la version locale de Medusa.

**Alternatives**
- `docker exec -it medusa-backend npx medusa migrations run`

### 3.2 Seed de données
**Commande**
```
docker compose run --rm backend npm run seed
```
**Explication**
- injecte des données de démo si `backend/data/seed.json` existe.

**Alternatives**
- `docker exec -it medusa-backend npm run seed`

### 3.3 Import CSV produits (Medusa)
**Commande**
```
docker compose run --rm backend npm run import:products
```
**Explication**
- importe des produits depuis `backend/data/products-import.csv` (upsert via `external_id`).

**Alternatives**
- `docker exec -it medusa-backend npm run import:products`
- `node backend/scripts/import-products.js --file backend/data/products-import.csv --dry-run`

**Doc**
- voir `DOC_IMPORT_PRODUITS.md`

### 3.4 Création utilisateur admin (Medusa)
**Commande**
```
docker exec -it medusa-backend medusa user -e admin@lucien.com -p supersecret
```
**Paramètres**
- `-e` : email de l’admin.
- `-p` : mot de passe.

**Alternatives**
- `medusa user --help`

### 3.5 Test DB via Node (diagnostic)
**Commande**
```
docker compose run --rm backend node -e "const { Client }=require('pg'); ... "
```
**Explication**
- `node -e` : exécute un script JS en ligne.
- `pg` : client PostgreSQL Node.

**Alternatives**
- script JS temporaire dans le conteneur.
- `psql` direct (plus simple si accès).

## 4. Storefront / Tests HTTP (curl)

### 4.1 Test de l’API Medusa
**Commande**
```
curl http://localhost:9000/store/products
```
**Paramètres**
- URL endpoint public Medusa.

**Alternatives**
- `curl -v ...`
- `http :9000/store/products` (httpie)

### 4.2 Test du storefront
**Commande**
```
curl http://localhost:8000
```
**Explication**
- vérifie que le site répond.

**Alternatives**
- `curl -I http://localhost:8000`

### 4.3 Test CORS
**Commande (public)**
```
curl -i -H "Origin: https://lsb.arauco.online" https://api-lsb.arauco.online/store/products
```
**Commande (LAN)**
```
curl -i -H "Origin: http://lsb.huitral.ruka.lan" http://api-lsb.huitral.ruka.lan/store/products
```
**Paramètres**
- `-i` : inclut les en-têtes.
- `-H` : ajoute un header `Origin`.

**Alternatives**
- `curl -v ...`
- DevTools navigateur (onglet Network).

## 5. Caddy / Reverse proxy (sur araucaria)

Le reverse proxy est géré par Caddy sur `araucaria`, pas sur `huitral`.

### 5.1 Statut Caddy
**Commande**
```
sudo systemctl status caddy
```

### 5.2 Logs Caddy
**Commandes**
```
sudo journalctl -u caddy -f
sudo journalctl -u caddy -n 200 --no-pager
```
**Paramètres**
- `-f` : suivi temps réel.

### 5.3 Éditer le Caddyfile
**Commande**
```
sudo nano /etc/caddy/Caddyfile
```

### 5.4 Valider la config
**Commande**
```
caddy validate --config /etc/caddy/Caddyfile
```
**Explication**
- vérifie la syntaxe avant rechargement.

### 5.5 Reload Caddy
**Commande**
```
sudo systemctl reload caddy
```
**Explication**
- recharge la config sans couper les connexions actives.

**Alternatives**
- `sudo systemctl restart caddy`
- `caddy reload --config /etc/caddy/Caddyfile`

## 6. DNS / Résolution (Windows + Linux)

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

### 6.2 DNS Linux
**Commandes**
```
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>`

## 7. Systemd / Logs système (journalctl)

### 7.1 Base
**Commandes**
```
sudo journalctl --disk-usage
sudo journalctl --list-boots
sudo journalctl -u <service> -n 50 --no-pager
sudo journalctl -u <service> -f
```
**Paramètres**
- `-u` : filtre par service.
- `-n` : n dernières lignes.
- `-f` : suivi temps réel.
- `-b` : dernier boot.
- `-S` : depuis une date (ex: `10 min ago`).
- `--no-pager` : pas de pagination.

## 8. Réseau / Ports (diagnostic)

### 8.1 Ports locaux
**Commandes**
```
ss -lntp | egrep '8000|9000|5432|6379'
netstat -lntp | egrep '8000|9000|5432|6379'
```
**Paramètres**
- `ss` : outil moderne (remplace netstat).
- `-l` listening, `-n` numérique, `-t` TCP, `-p` process.

**Alternatives**
- `lsof -iTCP -sTCP:LISTEN -n -P`

### 8.2 Firewall
**Commande**
```
sudo ufw status
```
**Alternatives**
- `sudo iptables -S`
- `sudo firewall-cmd --list-all`

## 9. Fichiers / Permissions

### 9.1 Vérifier présence d’un fichier
**Commandes**
```
ls -l docker-compose.yml
ls -l /etc/resolv.conf
```
**Explication**
- `-l` : détails (droits, owner).

**Alternatives**
- `stat <fichier>`

### 9.2 Corriger les permissions du dépôt
**Commande**
```
sudo chown -R "$USER":"$USER" /var/www/lucien-sens-bon
```
**Explication**
- redonne les droits à l’utilisateur courant.

**Alternatives**
- `sudo chgrp -R <groupe> <dossier>`
- `sudo chmod -R g+w <dossier>`

## 10. Git (workflow et maintenance)

### 10.1 État et staging
**Commandes**
```
git status
git add -A
git reset HEAD .env output*.txt
```
**Paramètres**
- `add -A` : indexe ajouts + modifs + suppressions.
- `reset HEAD ...` : retire du staging sans toucher au disque.

**Alternatives**
- `git add <fichier>`
- `git restore --staged <fichier>`

### 10.2 Commit avec identité temporaire
**Commande**
```
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"
```
**Explication**
- fixe l’identité uniquement pour cette commande.

**Alternatives**
- `git -c user.name="..." -c user.email="..." commit -m "..."`

### 10.3 Suivi de branche distante
**Commande**
```
git branch --set-upstream-to=origin/docs-git-dns
```
**Explication**
- associe la branche locale à la branche distante.

**Alternatives**
- `git push -u origin <branche>`

### 10.4 Mise à jour sans merge commit
**Commandes**
```
git pull --rebase
git fetch origin
git pull --rebase origin docs-git-dns
```
**Explication**
- `rebase` : rejoue les commits locaux au-dessus de la remote.

**Alternatives**
- `git pull --ff-only`

### 10.5 Aligner strictement sur la remote (ATTENTION)
**Commandes**
```
git fetch origin
git reset --hard origin/main
git clean -fd
```
**Explication**
- écrase les changements locaux + supprime les fichiers non suivis.

**Alternatives**
- `git stash push -u -m "wip"`

### 10.6 Stash pour rebase
**Commandes**
```
git stash push -u -m "wip avant rebase"
git stash pop
```
**Explication**
- sauvegarde temporaire des modifs non committés.

**Alternatives**
- `git add -A` + `git commit` (si vous préférez un commit).

### 10.7 Références Git
**Commandes**
```
git branch -a
git show-ref --heads
git show-ref --tags
```
**Explication**
- affiche les branches locales, distantes et tags.

## 11. Sauvegardes fichiers et dépôt

### 11.1 Sauvegarder les uploads
**Commande**
```
tar -czf /backups/medusa-uploads.tgz /var/www/lucien-sens-bon/backend/uploads
```
**Paramètres**
- `-c` : create, `-z` : gzip, `-f` : fichier output.

**Alternatives**
- `rsync -a` (sauvegarde incrémentale).

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

### 11.3 Sauvegarder le dépôt Git (bare)
**Commande**
```
git clone --mirror toshiro@chillka:/var/data/git/repositories/lucien-sens-bon.git \
  /backups/lucien-sens-bon.git
```
**Paramètres**
- `--mirror` : sauvegarde complète des refs/branches/tags.

**Alternatives**
- `git bundle create backup.bundle --all`

## 12. Édition / fichiers d’environnement

### 12.1 Copier le modèle `.env`
**Commande**
```
cp env-example .env
```
**Explication**
- crée un fichier `.env` local avec les variables par défaut.

**Alternatives**
- `cp -n env-example .env` (n’écrase pas si `.env` existe).

### 12.2 Éditer un fichier
**Commande**
```
vim .env
```
**Alternatives**
- `nano .env`
- `code .env`

## 13. Outils divers utiles

### 13.1 Tests HTTP rapides (headers only)
**Commande**
```
curl -I http://localhost:9000/store/products
```
**Explication**
- `-I` : en-têtes uniquement (plus rapide).

**Alternatives**
- `wget --spider <url>`

### 13.2 Recherche dans un conteneur
**Commande**
```
docker compose run --rm backend sh -c "rg -n \"update\\(\\{\\},\" node_modules/@medusajs/medusa/dist/services"
```
**Explication**
- `rg -n` : recherche rapide avec numéros de lignes.

**Alternatives**
- `grep -n <pattern> <fichier>`