# Documentation de Configuration - Formation Manager Itinova

**Version:** 7a737c05  
**Date:** 24 novembre 2025  
**Auteur:** Manus AI

---

## Vue d'ensemble

Ce document détaille toutes les variables de configuration et les paramètres nécessaires pour personnaliser et sécuriser votre installation de Formation Manager Itinova.

---

## Variables d'environnement

Toutes les variables d'environnement doivent être définies dans le fichier `.env` à la racine du projet. Ce fichier ne doit **jamais** être commité dans le dépôt Git pour des raisons de sécurité.

### Base de données

#### DATABASE_URL

**Type:** String (URL de connexion)  
**Requis:** Oui  
**Format:** `mysql://utilisateur:motdepasse@hote:port/nombase`

La chaîne de connexion complète à votre base de données MySQL ou TiDB. Cette URL contient toutes les informations nécessaires pour établir la connexion : utilisateur, mot de passe, hôte, port et nom de la base de données.

**Exemple:**
```
DATABASE_URL=mysql://formation_user:SecureP@ssw0rd@localhost:3306/formation_manager
```

**Recommandations de sécurité:**
- Utilisez un mot de passe fort d'au moins 16 caractères
- Créez un utilisateur dédié avec uniquement les permissions nécessaires
- Si possible, utilisez une connexion SSL/TLS (ajoutez `?ssl=true` à la fin de l'URL)
- Pour TiDB Cloud, utilisez toujours SSL et les certificats fournis

---

### Authentification et sécurité

#### JWT_SECRET

**Type:** String (clé secrète)  
**Requis:** Oui  
**Longueur minimale:** 32 caractères (64 recommandés)

La clé secrète utilisée pour signer les tokens JWT (JSON Web Tokens) qui gèrent les sessions utilisateur. Cette clé est critique pour la sécurité de votre application.

**Génération d'une clé sécurisée:**
```bash
openssl rand -hex 32
```

**Exemple:**
```
JWT_SECRET=a3f8b2c9d1e4f5a6b7c8d9e0f1a2b3c4d5e6f7a8b9c0d1e2f3a4b5c6d7e8f9a0
```

**Important:** Ne réutilisez jamais la même clé entre différents environnements (développement, staging, production).

#### OAUTH_SERVER_URL

**Type:** URL  
**Requis:** Oui  
**Valeur par défaut:** `https://api.manus.im`

L'URL du serveur OAuth Manus utilisé pour l'authentification des utilisateurs. Cette valeur ne doit généralement pas être modifiée sauf si vous utilisez une instance Manus personnalisée.

#### VITE_OAUTH_PORTAL_URL

**Type:** URL  
**Requis:** Oui  
**Valeur par défaut:** `https://auth.manus.im`

L'URL du portail de connexion Manus où les utilisateurs sont redirigés pour s'authentifier. Cette URL est utilisée côté client (frontend).

---

### Identité du propriétaire

#### OWNER_OPEN_ID

**Type:** String  
**Requis:** Oui

L'identifiant OpenID unique du propriétaire de l'application. Cet utilisateur aura automatiquement le rôle `admin` lors de sa première connexion et recevra les notifications système.

**Comment obtenir votre Open ID:**
1. Connectez-vous à votre compte Manus
2. Accédez à votre profil utilisateur
3. Copiez votre Open ID depuis les paramètres du compte

#### OWNER_NAME

**Type:** String  
**Requis:** Oui

Le nom complet du propriétaire de l'application, utilisé dans les notifications et les logs système.

**Exemple:**
```
OWNER_OPEN_ID=usr_abc123def456
OWNER_NAME=Olivier Pareige
```

---

### Configuration de l'application

#### VITE_APP_ID

**Type:** String  
**Requis:** Oui

L'identifiant unique de votre application Manus. Cette valeur est fournie lors de la création de votre application sur la plateforme Manus.

#### VITE_APP_TITLE

**Type:** String  
**Requis:** Non  
**Valeur par défaut:** `Gestion des Formations Manager Itinova`

Le titre de l'application affiché dans l'interface utilisateur, les onglets du navigateur et les emails. Vous pouvez personnaliser ce titre selon vos besoins.

**Exemple:**
```
VITE_APP_TITLE=Formation Manager - Itinova
```

#### VITE_APP_LOGO

**Type:** String (chemin relatif)  
**Requis:** Non  
**Valeur par défaut:** `/logo.png`

Le chemin vers le fichier logo de l'application. Le fichier doit être placé dans le répertoire `client/public/`. Le logo est affiché dans le header et les emails.

**Formats supportés:** PNG, SVG, JPG  
**Taille recommandée:** 200x50 pixels (ratio 4:1)

---

### APIs Manus intégrées

Ces variables sont généralement fournies automatiquement par la plateforme Manus lors du déploiement. Elles donnent accès aux services intégrés (LLM, stockage, notifications, etc.).

#### BUILT_IN_FORGE_API_URL

**Type:** URL  
**Requis:** Oui (pour les fonctionnalités avancées)

L'URL de base des APIs Manus Forge utilisées côté serveur.

#### BUILT_IN_FORGE_API_KEY

**Type:** String (clé API)  
**Requis:** Oui (pour les fonctionnalités avancées)

La clé d'authentification pour accéder aux APIs Manus côté serveur. Cette clé ne doit **jamais** être exposée côté client.

#### VITE_FRONTEND_FORGE_API_KEY

**Type:** String (clé API)  
**Requis:** Non

Une clé API distincte pour les appels côté client (frontend). Cette clé a des permissions limitées pour des raisons de sécurité.

#### VITE_FRONTEND_FORGE_API_URL

**Type:** URL  
**Requis:** Non

L'URL des APIs Manus accessibles depuis le frontend.

---

### Analytics (optionnel)

#### VITE_ANALYTICS_ENDPOINT

**Type:** URL  
**Requis:** Non

L'URL de votre service d'analytics (compatible Plausible/Umami). Si défini, les statistiques de visite seront envoyées à ce endpoint.

#### VITE_ANALYTICS_WEBSITE_ID

**Type:** String  
**Requis:** Non (sauf si VITE_ANALYTICS_ENDPOINT est défini)

L'identifiant unique de votre site dans le système d'analytics.

**Exemple:**
```
VITE_ANALYTICS_ENDPOINT=https://analytics.example.com
VITE_ANALYTICS_WEBSITE_ID=formation-manager-prod
```

---

### Configuration de l'environnement

#### NODE_ENV

**Type:** String  
**Requis:** Oui  
**Valeurs possibles:** `development`, `production`, `test`

Définit l'environnement d'exécution de l'application. En production, cette valeur **doit** être `production` pour activer les optimisations et désactiver les outils de développement.

#### PORT

**Type:** Number  
**Requis:** Non  
**Valeur par défaut:** `3000`

Le port sur lequel le serveur Express écoute les connexions. Si vous utilisez Nginx comme reverse proxy, gardez la valeur par défaut.

---

## Configuration SMTP (emails)

L'application utilise un serveur SMTP pour envoyer les emails automatiques (confirmations, rappels, teasers). La configuration SMTP se fait via l'interface web dans la section "Configuration SMTP" du menu.

### Paramètres SMTP requis

| Paramètre | Description | Exemple |
|-----------|-------------|---------|
| Hôte SMTP | Adresse du serveur SMTP | `smtp.gmail.com` |
| Port | Port du serveur (25, 465, 587) | `587` |
| Sécurité | TLS ou SSL | `TLS` |
| Utilisateur | Adresse email d'envoi | `noreply@itinova.org` |
| Mot de passe | Mot de passe ou app password | `****************` |

### Fournisseurs SMTP recommandés

**Gmail** : Gratuit jusqu'à 500 emails/jour. Nécessite un "App Password" si 2FA activé.  
**SendGrid** : 100 emails/jour gratuits, excellent pour la délivrabilité.  
**Amazon SES** : Très économique, $0.10 pour 1000 emails.  
**Mailgun** : 5000 emails/mois gratuits les 3 premiers mois.

### Test de configuration

Après avoir configuré SMTP, utilisez la fonction "Envoyer un email de test" dans l'interface pour vérifier que les emails sont bien envoyés et reçus.

---

## Configuration Nginx

### Certificat SSL

Pour activer HTTPS, vous devez obtenir un certificat SSL. La méthode recommandée est d'utiliser Let's Encrypt (gratuit) :

```bash
sudo apt install certbot python3-certbot-nginx
sudo certbot --nginx -d votre-domaine.com
```

Certbot configurera automatiquement Nginx et renouvellera le certificat avant expiration.

### Optimisations recommandées

**Compression Gzip** : Déjà activée dans la configuration fournie, réduit la bande passante de 70%.

**Cache des assets statiques** : Les fichiers CSS, JS et images sont mis en cache 1 an côté client pour améliorer les performances.

**HTTP/2** : Activé par défaut avec `http2` dans la directive `listen 443 ssl http2`.

**Rate limiting** : Pour protéger contre les attaques DDoS, ajoutez dans votre configuration Nginx :

```nginx
limit_req_zone $binary_remote_addr zone=api:10m rate=10r/s;

location /api/ {
    limit_req zone=api burst=20 nodelay;
    proxy_pass http://formation_backend;
}
```

---

## Sécurité avancée

### Rotation des secrets

Les clés sensibles (JWT_SECRET, mots de passe DB) doivent être changées régulièrement :

1. **Générer une nouvelle clé JWT**
2. **Mettre à jour `.env`**
3. **Redémarrer l'application**
4. **Tous les utilisateurs devront se reconnecter**

### Sauvegarde des configurations

Sauvegardez régulièrement votre fichier `.env` dans un gestionnaire de secrets sécurisé (pas dans Git) :

- **Vault** (HashiCorp)
- **AWS Secrets Manager**
- **Azure Key Vault**
- **1Password** (pour les petites équipes)

### Audit de sécurité

Vérifiez régulièrement :

- [ ] Les permissions de fichiers (`.env` doit être en 600)
- [ ] Les logs d'accès pour détecter des comportements suspects
- [ ] Les mises à jour de sécurité des dépendances (`pnpm audit`)
- [ ] La force des mots de passe de base de données
- [ ] L'expiration des certificats SSL

---

## Personnalisation

### Modification du logo

1. Placez votre nouveau logo dans `client/public/`
2. Mettez à jour `VITE_APP_LOGO` dans `.env`
3. Modifiez également `APP_LOGO` dans `client/src/const.ts`
4. Rebuild l'application : `pnpm run build`
5. Mettez à jour le favicon via l'interface de gestion

### Personnalisation des couleurs

Les couleurs de l'interface sont définies dans `client/src/index.css`. Modifiez les variables CSS dans la section `:root` pour personnaliser le thème :

```css
:root {
  --primary: 221.2 83.2% 53.3%;  /* Bleu principal */
  --secondary: 210 40% 96.1%;
  --accent: 210 40% 96.1%;
  /* ... */
}
```

### Ajout de fonctions personnalisées

Pour ajouter des fonctions spécifiques à votre organisation :

1. **Schéma** : Ajoutez les tables dans `drizzle/schema.ts`
2. **Backend** : Créez les fonctions dans `server/db.ts`
3. **API** : Ajoutez les procédures dans `server/routers.ts`
4. **Frontend** : Créez les pages dans `client/src/pages/`
5. **Navigation** : Ajoutez les liens dans `client/src/components/DashboardLayout.tsx`

---

## Troubleshooting

### L'application ne démarre pas

**Vérifiez le fichier `.env`** : Assurez-vous que toutes les variables requises sont définies.

**Testez la connexion DB** :
```bash
mysql -h HOST -u USER -p DATABASE
```

**Consultez les logs** :
```bash
sudo journalctl -u formation-manager -n 100
```

### Les emails ne sont pas envoyés

**Vérifiez la configuration SMTP** : Utilisez la fonction de test dans l'interface.

**Consultez les logs** : Les erreurs SMTP sont loguées dans les journaux système.

**Vérifiez les ports** : Assurez-vous que les ports SMTP (587, 465) ne sont pas bloqués par le pare-feu.

### Erreurs de base de données

**Migrations non appliquées** : Exécutez `pnpm db:push` pour synchroniser le schéma.

**Connexion refusée** : Vérifiez que MySQL est démarré et accessible.

**Erreur d'authentification** : Vérifiez les identifiants dans `DATABASE_URL`.

---

## Support

Pour toute question sur la configuration :

- **Documentation technique** : README.md du projet
- **Support Manus** : https://help.manus.im
- **Contact** : o.pareige@itinova.org

---

**Fin de la documentation de configuration**
