path: root/INSTALLATION.md

# Guide d'Installation Complet - Lucien-sens-bon

Ce guide détaille comment installer votre boutique MedusaJS (Backend) + Next.js (Frontend) sur votre serveur "huitral" avec Docker, et l'exposer via Caddy (reverse proxy sur araucaria).

## 1. Pré-requis

Assurez-vous d'avoir :
- **Docker** et **Docker Compose** installés sur `huitral`.
- Une base de données **PostgreSQL** accessible (version 12+ recommandée).
- **Caddy** installé sur `araucaria` (reverse proxy + HTTPS automatique).

## 1.1 Nomenclature DNS (ruka.lan)

Objectif : utiliser des noms internes stables sur `ruka.lan`, puis ouvrir les mêmes
noms en DNS public plus tard avec un minimum d'adaptations.

Format recommande :
```
<service>.<projet>.<site>.ruka.lan
```

Exemples pour Lucien Sens Bon (projet `lsb`) sur `huitral` :
- `www.lsb.huitral.ruka.lan` : storefront (site public)
- `api.lsb.huitral.ruka.lan` : API Medusa
- `admin.lsb.huitral.ruka.lan` : admin (optionnel, sinon /app sur l'API)

Conseil : gardez cette nomenclature pour tous vos projets afin de pouvoir passer
en DNS public sans changer les URLs dans l'application.

### 1.2 Configuration DNS (interne et public)

**Cas 1 — DNS interne (ruka.lan)**  
Créez des enregistrements A vers l'IP du serveur `huitral` :
- `www.lsb.huitral.ruka.lan` → `IP_DE_HUITRAL`
- `api.lsb.huitral.ruka.lan` → `IP_DE_HUITRAL`
- `admin.lsb.huitral.ruka.lan` → `IP_DE_HUITRAL` (optionnel)

**Cas 2 — Fichier hosts (temporaire/test local)**  
Si vous n'avez pas encore de DNS, ajoutez sur la machine cliente :
```
IP_DE_HUITRAL www.lsb.huitral.ruka.lan
IP_DE_HUITRAL api.lsb.huitral.ruka.lan
```

**Cas 3 — DNS public (arauco.online)**
Le DynDNS sync `*`, `@` et `git` pour `arauco.online`. Le wildcard `*` couvre tous
les sous-domaines, donc `lsb.arauco.online` et `api-lsb.arauco.online` résolvent
automatiquement vers l'IP publique. Pas besoin d'ajouter d'enregistrements.

URLs publiques utilisées :
- `https://lsb.arauco.online` → storefront
- `https://api-lsb.arauco.online` → API Medusa

**Bonnes pratiques**
- Utilisez les mêmes noms partout (DNS, Caddy, variables d'environnement).
- Évitez les ports dans les URLs publiques (Caddy s'en charge).
- Quand vous basculez en DNS public, mettez à jour `NEXT_PUBLIC_MEDUSA_BACKEND_URL`,
  `ADMIN_CORS` et `STORE_CORS` dans `.env`, puis rebuild le storefront.

### 1.3 DNS interne avec dnsmasq (araucaria)

Sur `araucaria`, ajoutez un fichier dédié pour ce projet :
```bash
sudo nano /etc/dnsmasq.d/lsb.conf
```

Contenu recommandé :
```
# Lucien Sens Bon - domaines publics
# Doivent pointer vers araucaria (Caddy) et non vers huitral directement,
# sinon les clients LAN contournent Caddy et tombent sur un port sans HTTPS.
address=/lsb.arauco.online/IP_DE_ARAUCARIA
address=/api-lsb.arauco.online/IP_DE_ARAUCARIA

# Lucien Sens Bon - domaines internes ruka.lan
# Pointent aussi vers araucaria (Caddy gere le proxy HTTP pour ces domaines).
address=/lsb.huitral.ruka.lan/IP_DE_ARAUCARIA
address=/api-lsb.huitral.ruka.lan/IP_DE_ARAUCARIA
```

Remplacez `IP_DE_ARAUCARIA` par l'IP LAN d'araucaria (ex: `192.168.99.50`).

> **Important** : ne pas pointer les domaines `arauco.online` vers huitral
> directement. Depuis l'extérieur, le DynDNS résout vers l'IP publique qui
> arrive sur araucaria (Caddy). Depuis le LAN, dnsmasq doit aussi envoyer
> vers araucaria, sinon les navigateurs se connectent à huitral:443 où rien
> n'écoute → `CONNECTION_REFUSED`.

Rechargez dnsmasq :
```bash
sudo systemctl restart dnsmasq
sudo systemctl status dnsmasq --no-pager
```

Tests rapides depuis un client :
```bash
dig +short lsb.arauco.online        # doit retourner IP_DE_ARAUCARIA
dig +short api-lsb.arauco.online    # doit retourner IP_DE_ARAUCARIA
dig +short lsb.huitral.ruka.lan     # doit retourner IP_DE_ARAUCARIA
dig +short api-lsb.huitral.ruka.lan # doit retourner IP_DE_ARAUCARIA
```

### 1.4 Procédure complète DNS (Windows + WSL)

WSL utilise le DNS de Windows. Il faut donc d'abord fixer Windows, puis WSL si besoin.

**A. Vérifier la résolution côté Windows**
```powershell
nslookup www.lsb.huitral.ruka.lan
```
Si l'IP n'est pas celle de `huitral`, passez à l'étape B.

**B. Forcer le DNS Windows sur araucaria**
1. Paramètres Windows → Réseau → Carte réseau → Propriétés IPv4  
2. DNS préféré = `IP_ARAUCARIA`  
3. Vider le cache DNS :
```powershell
ipconfig /flushdns
```

**C. Vérifier à nouveau côté Windows**
```powershell
nslookup www.lsb.huitral.ruka.lan
```

**D. WSL (si la résolution reste KO)**
Dans WSL :
```bash
ls -l /etc/resolv.conf
```
Si le lien est cassé (ex. vers `systemd/resolve`), recréez le fichier :
```bash
sudo rm -f /etc/resolv.conf
printf "nameserver IP_ARAUCARIA\n" | sudo tee /etc/resolv.conf
```

Empêcher WSL de régénérer `resolv.conf` :
```bash
sudo tee /etc/wsl.conf <<'EOF'
[network]
generateResolvConf = false
EOF
```

Redémarrer WSL **depuis Windows** :
```powershell
wsl --shutdown
```

Relancer WSL puis tester :
```bash
dig +short www.lsb.huitral.ruka.lan
```

## 2. Configuration Initiale

1. **Variables d'environnement** :
   Copiez le fichier d'exemple pour créer votre fichier de configuration réel :
   ```bash
   cp env-example .env
   ```

2. **Éditez le fichier `.env`** :
   Modifiez les valeurs, notamment la connexion à la base de données (`DATABASE_URL`).
   
   *Note : Si votre Postgres est sur la machine hôte (hors Docker), utilisez `host.docker.internal` comme hôte dans l'URL de connexion, ou l'IP locale du serveur.*

   Exemple de valeurs utilisées dans ce projet (PostgreSQL sur `npagnun`) :
   ```ini
   DATABASE_URL=postgres://luciensbdb:VOTRE_MOT_DE_PASSE_DB@192.168.99.35:5432/sens_bon_db
   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
   ```
   
   Édition avec `vim` :
   ```bash
   vim .env
   ```

## 2.1 Dépôt Git (Chillka) et récupération sur Huitral

Cette section est à faire **avant** le reste si vous déployez depuis Git.

### 2.1.1 Corriger le HEAD du dépôt bare (Chillka)

Sur `chillka` :
```bash
git --git-dir=/var/data/git/repositories/lucien-sens-bon.git symbolic-ref HEAD refs/heads/main
```

### 2.1.2 Cloner le projet sur `huitral`

Sur `huitral` :
```bash
cd /var/www
git clone toshiro@chillka:/var/data/git/repositories/lucien-sens-bon.git
cd lucien-sens-bon
git fetch origin
git checkout -b main origin/main
```

> Si votre branche distante est `master`, remplacez `main` par `master` dans les commandes ci‑dessus.

## 3. Installation et Démarrage

Lancez les conteneurs (cela va construire les images Backend et Storefront) :

```bash
docker compose up -d --build
```

> Sur Debian 13, utilisez de préférence `docker compose` (sans tiret) si le plugin est installé.

### 3.1 Commandes Docker utiles

```bash
# Statut des conteneurs
docker compose ps

# Logs en temps réel
docker compose logs -f

# Redémarrer tous les services
docker compose restart

# Arrêter tous les services
docker compose down
```

### 3.2 Dépannage Docker (erreurs courantes)

```bash
# Si "permission denied" sur /var/run/docker.sock
sudo usermod -aG docker $USER
# Déconnectez-vous/reconnectez-vous, puis retestez :
docker compose ps

# Si "npm ci" échoue (pas de package-lock.json)
# Le Dockerfile du storefront bascule automatiquement sur "npm install".
# Relancez ensuite le build :
docker compose build --no-cache storefront
docker compose up -d --build
```

Cela va démarrer 3 conteneurs :
- `medusa-backend` (API) sur le port 9000
- `medusa-storefront` (Site Web) sur le port 8000
- `medusa-redis` (Cache) sur le port 6379

## 4. Initialisation de la Base de Données

Une fois les conteneurs démarrés, vous devez initialiser la base de données Medusa (créer les tables) et créer un utilisateur administrateur.

1. **Lancer les migrations et le "seed" (données de démo)** :
   ```bash
   docker exec -it medusa-backend npm run seed
   ```
   *(Si cela échoue, assurez-vous que la base de données est vide ou que la connexion est correcte).*

2. **Créer un utilisateur Admin** :
   ```bash
   docker exec -it medusa-backend medusa user -e admin@lucien.com -p supersecret
   ```
   *(Remplacez l'email et le mot de passe par les vôtres).*

## 5. Configuration Caddy (Reverse Proxy sur araucaria)

Objectif : exposer proprement le site et l'API en HTTPS via Caddy sur `araucaria`,
sans exposer les ports 8000/9000 aux utilisateurs.

Architecture :
```
Internet → araucaria (Caddy, HTTPS) → huitral (Docker containers)
LAN      → araucaria (Caddy, HTTP)  → huitral (Docker containers)
```

### 5.1 Éditer le Caddyfile sur araucaria

Sur `araucaria`, éditez `/etc/caddy/Caddyfile` et ajoutez :

```caddyfile
# Lucien-sens-bon — acces public (HTTPS automatique)
lsb.arauco.online {
    reverse_proxy IP_DE_HUITRAL:8000
}

api-lsb.arauco.online {
    reverse_proxy IP_DE_HUITRAL:9000
}

# Lucien-sens-bon — acces LAN (HTTP, pas de certificat)
http://lsb.huitral.ruka.lan {
    reverse_proxy IP_DE_HUITRAL:8000
}

http://api-lsb.huitral.ruka.lan {
    reverse_proxy IP_DE_HUITRAL:9000
}
```

Remplacez `IP_DE_HUITRAL` par l'IP LAN de huitral (ex: `192.168.99.22`).

### 5.2 Recharger Caddy

```bash
sudo systemctl reload caddy
sudo systemctl status caddy
```

### 5.3 Bénéfices de ce reverse proxy
- **HTTPS automatique** : Caddy obtient et renouvelle les certificats Let's Encrypt.
- **URL propres** : accès en `https://lsb...` et `https://api-lsb...` sans ports.
- **Double accès** : public via `arauco.online`, local via `ruka.lan`.
- **Sécurité** : les ports 8000/9000 ne sont pas exposés directement.

### 5.4 Vérification Caddy

```bash
# Sur araucaria
sudo systemctl status caddy
curl -I https://lsb.arauco.online
curl -I https://api-lsb.arauco.online/store/products
```

## 6. Vérification

- **Storefront** : Accédez à `https://lsb.arauco.online` (ou `http://lsb.huitral.ruka.lan` en local). Vous devriez voir la page d'accueil.
- **Admin** : Accédez à `https://api-lsb.arauco.online/app` (le dashboard admin est servi par le backend). Connectez-vous avec l'utilisateur créé à l'étape 4.

## 7. Dépôt Git (Chillka) et déploiement sur Huitral

Cette section documente la mise en place du dépôt Git **bare** sur le serveur `chillka` et le déploiement du projet sur `huitral`.

### 7.1 Créer le dépôt bare sur `chillka`

Sur `chillka` (root ou sudo) :
```bash
sudo mkdir -p /var/data/git/repositories/lucien-sens-bon.git
sudo git init --bare /var/data/git/repositories/lucien-sens-bon.git
sudo chown -R toshiro:git-group-users /var/data/git/repositories/lucien-sens-bon.git
```

### 7.2 Corriger les permissions (si `Permission denied`)

Le dossier parent doit être accessible au groupe `git-group-users` :
```bash
sudo chgrp -R git-group-users /var/data/git/repositories
sudo chmod -R 2775 /var/data/git/repositories
```

### 7.3 Pousser le projet vers `chillka` (depuis votre machine locale)

Dans le dossier du projet :
```bash
git init
git add .
git commit -m "Initial commit: Medusa Backend + Storefront + Config"
git remote add origin toshiro@chillka:/var/data/git/repositories/lucien-sens-bon.git
git push -u origin main
```

> Si votre branche locale s'appelle `master`, utilisez :
> ```bash
> git push -u origin master
> ```

### 7.4 Récupérer le projet sur `huitral`

Sur `huitral` :
```bash
cd /var/www
git clone toshiro@chillka:/var/data/git/repositories/lucien-sens-bon.git lucien-sens-bon
cd lucien-sens-bon
```

### 7.5 Mise à jour quand `huitral` a déjà des changements

Objectif : pousser le code vers `chillka`, puis récupérer sur `huitral` **sans perdre les modifications locales**.

#### Option A — Conserver les changements de `huitral` (recommandé)

Sur `huitral` :
```bash
cd /var/www/lucien-sens-bon
git status
git add -A
git commit -m "wip: changements locaux huitral"
git push origin HEAD
```

Sur votre machine de dev (ou poste principal) :
```bash
git fetch origin
git checkout main
git merge origin/main
git merge origin/HEAD
git push origin main
```

Puis sur `huitral` :
```bash
cd /var/www/lucien-sens-bon
git fetch origin
git checkout main
git merge origin/main
```

#### Option B — Stasher temporairement sur `huitral`

Sur `huitral` :
```bash
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
```

Résoudre les conflits éventuels, puis :
```bash
git add -A
git commit -m "merge: main + wip huitral"
git push origin main
```

## 7. Paiements Crypto

Pour activer les paiements Crypto, nous vous conseillons d'installer un plugin comme `medusa-payment-coinbase` ou d'utiliser une intégration Stripe Crypto si disponible.

L'ajout d'un plugin se fait en 2 étapes :
1. Ajouter le package dans `backend/package.json`.
2. Ajouter la configuration dans `backend/medusa-config.js`.
3. Reconstruire le conteneur (`docker-compose up -d --build`).