# Guide de Déploiement - Gestion des Formations Manager Itinova

## Table des matières

1. [Prérequis](#prérequis)
2. [Installation locale](#installation-locale)
3. [Configuration](#configuration)
4. [Déploiement en production](#déploiement-en-production)
5. [Migration de base de données](#migration-de-base-de-données)
6. [Maintenance](#maintenance)
7. [Dépannage](#dépannage)

---

## Prérequis

### Environnement de développement

- **Node.js** : version 22.13.0 ou supérieure
- **pnpm** : gestionnaire de paquets (installé avec Node.js)
- **Base de données** : MySQL 8.0+ ou TiDB (compatible MySQL)
- **Git** : pour le contrôle de version

### Services externes (optionnels)

- **Resend** : pour l'envoi d'emails (clé API requise)
- **Plateforme Manus** : pour l'authentification OAuth (déjà configuré)

---

## Installation locale

### 1. Cloner le projet

```bash
# Si vous avez accès au dépôt Git
git clone <url-du-depot>
cd formation-manager-itinova

# Sinon, extraire l'archive
unzip formation-manager-itinova.zip
cd formation-manager-itinova
```

### 2. Installer les dépendances

```bash
pnpm install
```

### 3. Configurer les variables d'environnement

Créer un fichier `.env` à la racine du projet :

```env
# Base de données
DATABASE_URL=mysql://user:password@localhost:3306/formation_manager

# JWT Secret (générer une clé aléatoire sécurisée)
JWT_SECRET=votre_cle_secrete_tres_longue_et_aleatoire

# OAuth Manus (déjà configuré sur la plateforme)
OAUTH_SERVER_URL=https://api.manus.im
VITE_OAUTH_PORTAL_URL=https://login.manus.im
VITE_APP_ID=votre_app_id

# Propriétaire
OWNER_OPEN_ID=votre_open_id
OWNER_NAME=Nom du propriétaire

# Application
VITE_APP_TITLE=Gestion des Formations Manager Itinova
VITE_APP_LOGO=/logo.svg

# APIs Manus (optionnel)
BUILT_IN_FORGE_API_URL=https://forge.manus.im
BUILT_IN_FORGE_API_KEY=votre_cle_api
VITE_FRONTEND_FORGE_API_KEY=votre_cle_frontend
VITE_FRONTEND_FORGE_API_URL=https://forge.manus.im

# Analytics (optionnel)
VITE_ANALYTICS_ENDPOINT=https://analytics.manus.im
VITE_ANALYTICS_WEBSITE_ID=votre_website_id
```

### 4. Initialiser la base de données

```bash
# Créer la base de données
mysql -u root -p -e "CREATE DATABASE formation_manager CHARACTER SET utf8mb4 COLLATE utf8mb4_unicode_ci;"

# Appliquer les migrations
pnpm db:push
```

### 5. Créer l'utilisateur administrateur

L'utilisateur administrateur est créé automatiquement au premier lancement :

- **Identifiant** : `adminServFormation`
- **Mot de passe** : `Itinova69!`
- **Email** : `admin@formation.local` (modifiable)

### 6. Lancer l'application en développement

```bash
pnpm dev
```

L'application sera accessible à l'adresse : `http://localhost:3000`

---

## Configuration

### Configuration SMTP (Resend)

1. Créer un compte sur [Resend](https://resend.com)
2. Générer une clé API
3. Se connecter à l'application avec l'utilisateur admin
4. Aller dans **Configuration SMTP**
5. Saisir :
   - **Clé API Resend** : votre clé API
   - **Email expéditeur** : votre email vérifié sur Resend
   - **Nom de l'expéditeur** : Itinova Formation
6. Activer le mode **Production**
7. Tester l'envoi

### Personnalisation des templates d'emails

1. Se connecter en tant qu'administrateur
2. Aller dans **Templates d'emails**
3. Modifier les templates selon vos besoins :
   - Email de confirmation d'inscription
   - Email teaser
   - Email de rappel J-7

### Gestion des utilisateurs

1. Se connecter en tant qu'administrateur
2. Aller dans **Utilisateurs**
3. Créer de nouveaux utilisateurs avec identifiant et mot de passe
4. Attribuer le rôle **admin** ou **user**

**Note** : L'utilisateur `adminServFormation` ne peut pas être supprimé et garantit un accès permanent à l'administration.

---

## Déploiement en production

### Option 1 : Déploiement sur la plateforme Manus (recommandé)

L'application est déjà configurée pour la plateforme Manus. Pour déployer :

1. Se connecter à l'interface de gestion Manus
2. Créer un checkpoint via le bouton **Save Checkpoint**
3. Cliquer sur le bouton **Publish** dans l'en-tête
4. Configurer le domaine personnalisé si nécessaire
5. Publier l'application

**Avantages** :
- Déploiement automatique
- SSL/TLS automatique
- Scaling automatique
- Base de données TiDB incluse
- Pas de configuration serveur nécessaire

### Option 2 : Déploiement manuel sur serveur VPS

#### Prérequis serveur

- Ubuntu 22.04 LTS ou supérieur
- 2 CPU, 4 GB RAM minimum
- Node.js 22.13.0+
- MySQL 8.0+ ou MariaDB 10.6+
- Nginx (reverse proxy)
- Certbot (SSL/TLS)

#### Étapes de déploiement

1. **Préparer le serveur**

```bash
# Mettre à jour le système
sudo apt update && sudo apt upgrade -y

# Installer Node.js 22
curl -fsSL https://deb.nodesource.com/setup_22.x | sudo -E bash -
sudo apt install -y nodejs

# Installer pnpm
npm install -g pnpm

# Installer MySQL
sudo apt install -y mysql-server

# Installer Nginx
sudo apt install -y nginx

# Installer Certbot
sudo apt install -y certbot python3-certbot-nginx
```

2. **Déployer l'application**

```bash
# Créer un utilisateur dédié
sudo useradd -m -s /bin/bash formation
sudo su - formation

# Cloner ou copier le projet
cd /home/formation
# Copier les fichiers du projet ici

# Installer les dépendances
pnpm install

# Configurer les variables d'environnement
cp .env.example .env
nano .env

# Build de production
pnpm build
```

3. **Configurer le service systemd**

Créer le fichier `/etc/systemd/system/formation-manager.service` :

```ini
[Unit]
Description=Formation Manager Itinova
After=network.target mysql.service

[Service]
Type=simple
User=formation
WorkingDirectory=/home/formation/formation-manager-itinova
ExecStart=/usr/bin/pnpm start
Restart=on-failure
RestartSec=10
Environment=NODE_ENV=production

[Install]
WantedBy=multi-user.target
```

Activer et démarrer le service :

```bash
sudo systemctl daemon-reload
sudo systemctl enable formation-manager
sudo systemctl start formation-manager
sudo systemctl status formation-manager
```

4. **Configurer Nginx**

Créer le fichier `/etc/nginx/sites-available/formation-manager` :

```nginx
server {
    listen 80;
    server_name votre-domaine.com;

    location / {
        proxy_pass http://localhost:3000;
        proxy_http_version 1.1;
        proxy_set_header Upgrade $http_upgrade;
        proxy_set_header Connection 'upgrade';
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_set_header X-Forwarded-Proto $scheme;
        proxy_cache_bypass $http_upgrade;
    }

    client_max_body_size 10M;
}
```

Activer le site :

```bash
sudo ln -s /etc/nginx/sites-available/formation-manager /etc/nginx/sites-enabled/
sudo nginx -t
sudo systemctl reload nginx
```

5. **Configurer SSL/TLS avec Let's Encrypt**

```bash
sudo certbot --nginx -d votre-domaine.com
```

---

## Migration de base de données

### Appliquer les migrations

```bash
# En développement
pnpm db:push

# En production (avec sauvegarde)
# 1. Sauvegarder la base de données
mysqldump -u root -p formation_manager > backup_$(date +%Y%m%d_%H%M%S).sql

# 2. Appliquer les migrations
pnpm db:push
```

### Restaurer une sauvegarde

```bash
mysql -u root -p formation_manager < backup_20250123_120000.sql
```

---

## Maintenance

### Logs de l'application

```bash
# Logs systemd
sudo journalctl -u formation-manager -f

# Logs Nginx
sudo tail -f /var/log/nginx/access.log
sudo tail -f /var/log/nginx/error.log
```

### Mise à jour de l'application

```bash
# Arrêter le service
sudo systemctl stop formation-manager

# Mettre à jour le code
cd /home/formation/formation-manager-itinova
git pull origin main

# Installer les nouvelles dépendances
pnpm install

# Appliquer les migrations
pnpm db:push

# Rebuild
pnpm build

# Redémarrer le service
sudo systemctl start formation-manager
```

### Sauvegarde automatique

Créer un script de sauvegarde `/home/formation/backup.sh` :

```bash
#!/bin/bash
BACKUP_DIR="/home/formation/backups"
DATE=$(date +%Y%m%d_%H%M%S)

# Créer le répertoire de sauvegarde
mkdir -p $BACKUP_DIR

# Sauvegarder la base de données
mysqldump -u root -p formation_manager > $BACKUP_DIR/db_$DATE.sql

# Compresser
gzip $BACKUP_DIR/db_$DATE.sql

# Supprimer les sauvegardes de plus de 30 jours
find $BACKUP_DIR -name "db_*.sql.gz" -mtime +30 -delete

echo "Sauvegarde terminée : $BACKUP_DIR/db_$DATE.sql.gz"
```

Ajouter une tâche cron :

```bash
crontab -e

# Sauvegarde quotidienne à 2h du matin
0 2 * * * /home/formation/backup.sh
```

---

## Dépannage

### L'application ne démarre pas

1. Vérifier les logs :
   ```bash
   sudo journalctl -u formation-manager -n 50
   ```

2. Vérifier la connexion à la base de données :
   ```bash
   mysql -u root -p -e "SHOW DATABASES;"
   ```

3. Vérifier les variables d'environnement dans `.env`

### Erreur de connexion à la base de données

1. Vérifier que MySQL est démarré :
   ```bash
   sudo systemctl status mysql
   ```

2. Tester la connexion :
   ```bash
   mysql -u user -p formation_manager
   ```

3. Vérifier l'URL de connexion dans `.env`

### Les emails ne sont pas envoyés

1. Vérifier la configuration SMTP dans l'interface admin
2. Vérifier que la clé API Resend est valide
3. Vérifier que l'email expéditeur est vérifié sur Resend
4. Consulter les logs de l'application

### Problème de permissions

```bash
# Corriger les permissions
sudo chown -R formation:formation /home/formation/formation-manager-itinova
sudo chmod -R 755 /home/formation/formation-manager-itinova
```

### L'authentification locale ne fonctionne pas

1. Vérifier que `JWT_SECRET` est défini dans `.env`
2. Vérifier que l'utilisateur `adminServFormation` existe dans la base de données
3. Réinitialiser le mot de passe si nécessaire via SQL :

```sql
-- Le mot de passe hashé pour "Itinova69!"
UPDATE users 
SET password = '$2a$10$...' 
WHERE username = 'adminServFormation';
```

---

## Support

Pour toute question ou problème :

1. Consulter la documentation complète dans le dossier `/docs`
2. Vérifier les logs de l'application
3. Contacter l'équipe de développement

---

**Version** : 1.0.0  
**Dernière mise à jour** : 23 novembre 2025