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

## 1. Pré-requis

Assurez-vous d'avoir :
- **Docker** et **Docker Compose** installés.
- Une base de données **PostgreSQL** accessible (version 12+ recommandée).
- **Apache** installé sur la machine hôte.

## 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**
Créez des enregistrements A (et AAAA si IPv6) vers l'IP publique :
- `www.lucien-sens-bon.com` → `IP_PUBLIQUE`
- `api.lucien-sens-bon.com` → `IP_PUBLIQUE`

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

### 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 - ruka.lan
address=/www.lsb.huitral.ruka.lan/IP_DE_HUITRAL
address=/api.lsb.huitral.ruka.lan/IP_DE_HUITRAL
address=/admin.lsb.huitral.ruka.lan/IP_DE_HUITRAL
```

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

Tests rapides depuis un client :
```bash
dig +short www.lsb.huitral.ruka.lan
dig +short api.lsb.huitral.ruka.lan
```

### 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=http://api.lucien-sens-bon.com
   ADMIN_CORS=http://api.lucien-sens-bon.com
   STORE_CORS=http://lucien-sens-bon.com
   ```
   
   É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 Apache (Reverse Proxy)

Objectif : exposer proprement le site et l'API en HTTP/HTTPS via Apache, sans exposer les ports 8000/9000 aux utilisateurs.

### 5.1 Créer le vhost Apache
1. **Copiez la configuration fournie** :
   ```bash
   sudo cp apache-vhost.conf /etc/apache2/sites-available/lucien.conf
   ```
   *Le fichier définit 2 vhosts :*
   - `www.lsb.huitral.ruka.lan` → storefront (port 8000)
   - `api.lsb.huitral.ruka.lan` → backend Medusa (port 9000)

2. **Vérifiez/ajustez les ServerName** selon vos DNS internes/publics.  
   Si vous n'avez pas encore de DNS, ajoutez temporairement dans `/etc/hosts` :
   ```
   127.0.0.1 www.lsb.huitral.ruka.lan
   127.0.0.1 api.lsb.huitral.ruka.lan
   ```

### 5.2 Activer les modules nécessaires
```bash
sudo a2enmod proxy
sudo a2enmod proxy_http
```
*(optionnel mais recommandé si vous ajoutez du HTTPS plus tard : `headers`, `rewrite`)*  
```bash
sudo a2enmod headers
sudo a2enmod rewrite
```

### 5.3 Activer le site et redémarrer Apache
```bash
sudo a2ensite lucien.conf
sudo apache2ctl configtest
sudo service apache2 restart
```

### 5.4 Bénéfices de ce reverse proxy
- **URL propres** : accès en `http://www...` et `http://api...` sans ports.
- **Centralisation HTTPS** : un seul endroit pour gérer les certificats (Certbot).
- **Sécurité** : vous pouvez restreindre l'accès direct aux ports 8000/9000.
- **Logs clairs** : logs séparés pour storefront et API.

### 5.5 Option HTTPS (recommandé en production)
```bash
sudo certbot --apache -d www.lsb.huitral.ruka.lan -d api.lsb.huitral.ruka.lan
```

## 6. Vérification

- **Storefront** : Accédez à `http://lucien-sens-bon.com` (ou votre domaine). Vous devriez voir la page d'accueil.
- **Admin** : Accédez à `http://api.lucien-sens-bon.com/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`).