aivanov_database/omop/RUN_SCRIPT_GUIDE.md

# 🚀 Guide du Script run.sh

## Vue d'ensemble

Le script `run.sh` est un **script complet** qui démarre toute la stack OMOP Pipeline avec vérifications et gestion d'erreurs.

---

## Utilisation

### Démarrage simple

```bash
cd omop
./run.sh
```

C'est tout ! Le script s'occupe de tout.

---

## Ce que fait le script

### 1. Vérifications préalables ✅

Le script vérifie automatiquement :
- ✅ Python 3 est installé
- ✅ Node.js est installé
- ✅ npm est installé
- ✅ PostgreSQL est accessible
- ✅ Dépendances Python installées
- ✅ Dépendances npm installées
- ✅ Connexion à la base de données

### 2. Installation automatique 📦

Si des dépendances manquent, le script les installe automatiquement :
- Dépendances Python (`requirements.txt` + `requirements-api.txt`)
- Dépendances npm (`frontend/node_modules`)

### 3. Démarrage de la stack 🚀

Le script démarre dans l'ordre :
1. **API FastAPI** (port 8000)
2. **Frontend React** (port 4400)

### 4. Monitoring 📊

Le script :
- Vérifie que chaque service démarre correctement
- Affiche les PIDs des processus
- Crée des logs dans `logs/api.log` et `logs/frontend.log`
- Attend les signaux d'arrêt (Ctrl+C)

### 5. Arrêt propre 🛑

Quand tu appuies sur Ctrl+C :
- Le script arrête proprement l'API
- Le script arrête proprement le frontend
- Les processus sont nettoyés

---

## Ports utilisés

| Service | Port | URL |
|---------|------|-----|
| **Frontend** | 4400 | http://localhost:4400 |
| **API** | 8000 | http://localhost:8000 |
| **Docs API** | 8000 | http://localhost:8000/docs |

---

## Logs

Les logs sont automatiquement créés dans :
- `logs/api.log` - Logs de l'API FastAPI
- `logs/frontend.log` - Logs du frontend React

Pour consulter les logs en temps réel :

```bash
# Logs API
tail -f logs/api.log

# Logs Frontend
tail -f logs/frontend.log
```

---

## Messages du script

### Messages d'information (bleu)
```
[INFO] Vérification de Python...
[INFO] Démarrage de l'API FastAPI...
```

### Messages de succès (vert)
```
[SUCCESS] Python trouvé: Python 3.12.3
[SUCCESS] API démarrée (PID: 12345)
```

### Messages d'avertissement (jaune)
```
[WARNING] Dépendances Python manquantes, installation...
[WARNING] Impossible de se connecter à la base de données
```

### Messages d'erreur (rouge)
```
[ERROR] Python 3 n'est pas installé
[ERROR] Échec du démarrage de l'API
```

---

## Exemple de sortie

```
╔═══════════════════════════════════════════════════════════╗
║                                                           ║
║           🚀 OMOP PIPELINE - STACK COMPLÈTE 🚀            ║
║                                                           ║
╚═══════════════════════════════════════════════════════════╝

[INFO] Vérification de Python...
[SUCCESS] Python trouvé: Python 3.12.3
[INFO] Vérification de Node.js...
[SUCCESS] Node.js trouvé: v20.11.0
[INFO] Vérification de npm...
[SUCCESS] npm trouvé: v10.2.4
[INFO] Vérification de PostgreSQL...
[SUCCESS] PostgreSQL trouvé: psql (PostgreSQL) 16.11
[INFO] Vérification des dépendances Python...
[SUCCESS] Dépendances Python OK
[INFO] Vérification des dépendances frontend...
[SUCCESS] Dépendances frontend OK
[INFO] Vérification de la connexion PostgreSQL...
[SUCCESS] Connexion à la base de données OK

[INFO] ═══════════════════════════════════════════════════════════
[INFO]               DÉMARRAGE DE LA STACK
[INFO] ═══════════════════════════════════════════════════════════

[INFO] Démarrage de l'API FastAPI...
[SUCCESS] API démarrée (PID: 12345)
[SUCCESS] API disponible sur: http://localhost:8000
[SUCCESS] Documentation API: http://localhost:8000/docs
[INFO] Démarrage du frontend React...
[SUCCESS] Frontend démarré (PID: 12346)
[SUCCESS] Frontend disponible sur: http://localhost:4400

[SUCCESS] ═══════════════════════════════════════════════════════════
[SUCCESS]            ✅ STACK OMOP PIPELINE DÉMARRÉE ✅
[SUCCESS] ═══════════════════════════════════════════════════════════

  📊 Frontend:        http://localhost:4400
  🔌 API:             http://localhost:8000
  📚 Documentation:   http://localhost:8000/docs

  📝 Logs API:        logs/api.log
  📝 Logs Frontend:   logs/frontend.log

[INFO] Appuyez sur Ctrl+C pour arrêter la stack
```

---

## Arrêt de la stack

### Arrêt normal

Appuie sur **Ctrl+C** dans le terminal où le script tourne :

```
^C
[WARNING] Arrêt de la stack OMOP Pipeline...
[INFO] Arrêt de l'API (PID: 12345)
[INFO] Arrêt du frontend (PID: 12346)
[SUCCESS] Stack arrêtée proprement
```

### Arrêt forcé

Si le script ne répond pas, tu peux forcer l'arrêt :

```bash
# Trouver les processus
ps aux | grep "run_api.py\|vite"

# Tuer les processus
kill -9 <PID_API> <PID_FRONTEND>
```

---

## Troubleshooting

### Le script ne démarre pas

**Problème** : `Permission denied`

**Solution** :
```bash
chmod +x run.sh
./run.sh
```

### Python n'est pas trouvé

**Problème** : `[ERROR] Python 3 n'est pas installé`

**Solution** :
```bash
# Vérifier Python
python3 --version

# Installer Python si nécessaire
sudo apt install python3  # Ubuntu/Debian
```

### Node.js n'est pas trouvé

**Problème** : `[ERROR] Node.js n'est pas installé`

**Solution** :
```bash
# Vérifier Node.js
node --version

# Installer Node.js si nécessaire
# Voir: https://nodejs.org/
```

### PostgreSQL n'est pas accessible

**Problème** : `[WARNING] Impossible de se connecter à la base de données`

**Solution** :
```bash
# Vérifier que PostgreSQL tourne
sudo systemctl status postgresql

# Démarrer PostgreSQL si nécessaire
sudo systemctl start postgresql

# Tester la connexion
psql -U dom -d omop_cdm
```

### L'API ne démarre pas

**Problème** : `[ERROR] Échec du démarrage de l'API`

**Solution** :
```bash
# Consulter les logs
cat logs/api.log

# Vérifier que le port 8000 est libre
lsof -i :8000

# Tester manuellement
python3 run_api.py
```

### Le frontend ne démarre pas

**Problème** : `[ERROR] Échec du démarrage du frontend`

**Solution** :
```bash
# Consulter les logs
cat logs/frontend.log

# Vérifier que le port 4400 est libre
lsof -i :4400

# Réinstaller les dépendances
cd frontend
rm -rf node_modules package-lock.json
npm install
```

---

## Comparaison avec start_web.sh

| Fonctionnalité | run.sh | start_web.sh |
|----------------|--------|--------------|
| Vérifications préalables | ✅ Complètes | ❌ Basiques |
| Messages colorés | ✅ Oui | ❌ Non |
| Logs dans fichiers | ✅ Oui | ❌ Non |
| Gestion d'erreurs | ✅ Avancée | ⚠️ Basique |
| Arrêt propre | ✅ Oui | ✅ Oui |
| Installation auto | ✅ Oui | ✅ Oui |
| Vérification BDD | ✅ Oui | ❌ Non |

**Recommandation** : Utilise `run.sh` pour un démarrage complet et robuste.

---

## Configuration

### Changer les ports

Pour changer les ports, modifie :

**Frontend** (port 4400) :
```javascript
// frontend/vite.config.js
server: {
  port: 4400,  // Changer ici
  ...
}
```

**API** (port 8000) :
```python
# run_api.py
uvicorn.run(
    "src.api.main:app",
    host="0.0.0.0",
    port=8000,  # Changer ici
    ...
)
```

N'oublie pas de mettre à jour le CORS dans `src/api/main.py` :
```python
allow_origins=["http://localhost:4400", ...]
```

---

## Utilisation avancée

### Démarrer en mode debug

```bash
# Modifier run_api.py pour activer le debug
# Puis lancer
./run.sh
```

### Démarrer uniquement l'API

```bash
python3 run_api.py
```

### Démarrer uniquement le frontend

```bash
cd frontend
npm run dev
```

### Consulter les logs en temps réel

```bash
# Terminal 1 - Logs API
tail -f logs/api.log

# Terminal 2 - Logs Frontend
tail -f logs/frontend.log

# Terminal 3 - Lancer la stack
./run.sh
```

---

## Intégration CI/CD

Le script peut être utilisé dans un pipeline CI/CD :

```yaml
# .github/workflows/deploy.yml
- name: Start OMOP Stack
  run: |
    cd omop
    ./run.sh &
    sleep 10
    
- name: Run tests
  run: |
    curl http://localhost:8000/health
    curl http://localhost:4400
```

---

## Résumé

**Commande unique** :
```bash
./run.sh
```

**Résultat** :
- ✅ Vérifications complètes
- ✅ Installation automatique
- ✅ Démarrage de la stack
- ✅ Logs dans fichiers
- ✅ Arrêt propre

**Accès** :
- Frontend : http://localhost:4400
- API : http://localhost:8000
- Docs : http://localhost:8000/docs

**Simple, robuste, complet ! 🚀**