# Déploiement manuel sur serveur Linux

Guide complet pour installer et faire tourner **Mercator** (API FastAPI + frontend Vite)
sur un serveur Linux **sans Docker**.

---

## Prérequis

| Logiciel | Version minimale | Vérification |
|----------|-----------------|--------------|
| Python   | 3.11+           | `python3 --version` |
| Node.js  | 18+             | `node --version` |
| npm      | 9+              | `npm --version` |
| Git      | any             | `git --version` |

Installation rapide sur Ubuntu/Debian :

```bash
# Python 3.11
sudo apt install python3.11 python3.11-venv python3.11-dev

# Node.js 20 LTS (via NodeSource)
curl -fsSL https://deb.nodesource.com/setup_20.x | sudo -E bash -
sudo apt install nodejs
```

---

## Déploiement rapide (script automatique)

```bash
# 1. Cloner le dépôt
git clone <url-du-repo> /opt/mercator
cd /opt/mercator

# 2. Lancer le script de déploiement
bash scripts/deploy.sh

# 3. Éditer .env (obligatoire — renseigner OPENAI_API_KEY)
nano .env

# 4. Démarrer le serveur
source .venv/bin/activate
uvicorn api:app --host 0.0.0.0 --port 8000
```

Le script `deploy.sh` effectue automatiquement :
- vérification des prérequis
- création du virtualenv Python (`.venv/`)
- installation des dépendances Python
- build du frontend Vite (`frontend/v2/dist/`)
- création du fichier `.env` depuis `.env.example`

---

## Déploiement étape par étape

### 1. Cloner le dépôt

```bash
git clone <url-du-repo> /opt/mercator
cd /opt/mercator
```

### 2. Configurer l'environnement Python

```bash
python3 -m venv .venv
source .venv/bin/activate
pip install -r requirements.txt
```

### 3. Construire le frontend

Le frontend Vite **doit être compilé** avant de démarrer le serveur.
FastAPI monte `frontend/v2/dist/assets/` au démarrage — si le dossier est absent, le serveur crashe.

```bash
bash scripts/build_frontend.sh
```

Vérification :

```bash
ls frontend/v2/dist/
# doit afficher : index.html  assets/
```

Pour reconstruire proprement (après une mise à jour du code frontend) :

```bash
bash scripts/build_frontend.sh --clean
```

### 4. Configurer les variables d'environnement

```bash
cp .env.example .env
nano .env   # ou vim, etc.
```

Variables **obligatoires** :

```env
OPENAI_API_KEY=sk-proj-...
```

Variables optionnelles — laisser vide pour désactiver :

```env
API_KEY=                    # auth sur /ask et /analysis
LANGFUSE_PUBLIC_KEY=        # observabilité Langfuse
LANGFUSE_SECRET_KEY=
LANGFUSE_HOST=http://localhost:3000
ORS_API_KEY=                # isochrones voiture
OTP_URL=http://localhost:8080  # isochrones transports
```

### 5. Démarrer le serveur

**Manuellement (développement/test) :**

```bash
source .venv/bin/activate
uvicorn api:app --host 0.0.0.0 --port 8000
```

Le serveur est accessible sur `http://<ip-serveur>:8000`.

**En production (recommandé : plusieurs workers) :**

```bash
uvicorn api:app --host 0.0.0.0 --port 8000 --workers 2
```

> `--workers` > 1 désactive le mode `--reload`.
> Ne pas dépasser le nombre de cœurs CPU.

---

## Service systemd (démarrage automatique)

Pour que le serveur redémarre automatiquement au boot et après une erreur :

```bash
# Créer un utilisateur dédié (optionnel mais recommandé)
sudo useradd -r -s /bin/false -d /opt/mercator mercator
sudo chown -R mercator:mercator /opt/mercator

# Installer le service (le script patche les chemins automatiquement)
bash scripts/deploy.sh --with-systemd

# Démarrer et vérifier
sudo systemctl start mercator
sudo systemctl status mercator
```

Commandes utiles :

```bash
sudo systemctl stop mercator       # arrêter
sudo systemctl restart mercator    # redémarrer
sudo journalctl -u mercator -f     # suivre les logs en temps réel
sudo journalctl -u mercator --since "1 hour ago"
```

Le fichier source du service est `scripts/mercator.service`.
Les placeholders `__REPO_ROOT__` et `__VENV__` sont remplacés par le script.

---

## Mise à jour

```bash
cd /opt/mercator
git pull

# Reconstruire le frontend si des fichiers dans frontend/v2/src/ ont changé
bash scripts/build_frontend.sh

# Réinstaller les dépendances si requirements.txt a changé
source .venv/bin/activate
pip install -r requirements.txt

# Redémarrer le serveur
sudo systemctl restart mercator   # si systemd
# ou relancer manuellement
```

---

## URLs disponibles après démarrage

| URL | Description |
|-----|-------------|
| `http://localhost:8000/v2` | **Carte Mercator** (frontend Vite) |
| `http://localhost:8000/docs` | Documentation API interactive (Swagger) |
| `http://localhost:8000/health` | État du service (healthcheck) |
| `http://localhost:8000/metrics` | Métriques de performance |
| `http://localhost:8000/dashboard` | Dashboard de monitoring |
| `http://localhost:8000/map` | Carte sécurité legacy |
| `http://localhost:8000/flood-map` | Carte zones inondables legacy |

---

## Tests de déploiement

Les smoke tests vérifient qu'un serveur **live** répond correctement.
Ils sont **désactivés par défaut** et nécessitent un serveur en cours d'exécution.

```bash
# Contre localhost:8000
pytest tests/test_deployment.py -v --run-deployment

# Contre un serveur distant
pytest tests/test_deployment.py -v --run-deployment --base-url http://192.168.1.10:8000

# Avec authentification API
pytest tests/test_deployment.py -v --run-deployment --api-key ma-cle-secrete
```

Ce que testent les smoke tests :

| Catégorie | Tests |
|-----------|-------|
| `TestHealth` | `/health` → `{"statut":"ok"}`, `/metrics` → clés attendues |
| `TestFrontend` | `/v2` → HTML avec titre Mercator, `/assets/*.js` → JavaScript servi |
| `TestDataEndpoints` | `/map-data` → GeoJSON IRIS, `/api/v2/iris-pressure/`, `/nearby-sales`, `/poi`, `/flood-zones`, `/flood-polygons` |
| `TestRouting` | `/` → redirect `/docs`, `/docs` → HTML |

Tests unitaires (pas de serveur requis) :

```bash
pytest tests/test_api.py -v          # tests HTTP sans tokens
pytest tests/test_tools.py -v        # outils individuels
pytest tests/test_analysis.py -v     # algorithme d'estimation
```

---

## Reconstruction des données

Si les fichiers de données (`data/immobilier.db`, `data/2026/*.json`) sont absents ou obsolètes,
relancer les scripts de construction dans l'ordre (voir `build_all.sh` pour les détails) :

```bash
source .venv/bin/activate
bash build_all.sh
```

> Certains scripts téléchargent des données volumineuses (DVF, IGN, GEORISQUES).
> Compter 30–60 minutes pour une reconstruction complète.

---

## Dépannage

**Le serveur crashe au démarrage avec `RuntimeError: StaticFiles directory does not exist`**

Le frontend n'a pas été compilé. Lancer :
```bash
bash scripts/build_frontend.sh
```

**`/v2` retourne 404**

Vérifier que `frontend/v2/dist/index.html` existe.

**Les assets JS donnent 404 (`/assets/main-xxx.js`)**

Vérifier que `frontend/v2/dist/assets/` contient des fichiers `.js`.
Reconstruire avec `bash scripts/build_frontend.sh --clean`.

**`npm ci` échoue avec des erreurs de plateforme (`@rollup/rollup-linux-x64-gnu`)**

Normal sur un serveur Linux si le projet a été développé sur Windows/macOS.
`npm ci` installe les binaires natifs pour la plateforme courante automatiquement.

**Port 8000 déjà utilisé**

```bash
sudo lsof -i :8000
# ou
uvicorn api:app --host 0.0.0.0 --port 8080
```

**Logs en temps réel**

```bash
# Avec systemd
sudo journalctl -u mercator -f

# Sans systemd (le serveur écrit dans le terminal)
# Ou consulter uvicorn.log si configuré
```