formation-manager-itinova/CONFIGURATION.md

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:

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) :

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 :

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 :

: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 :

mysql -h HOST -u USER -p DATABASE

Consultez les logs :

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