formation-manager-itinova/GUIDE_DEPLOIEMENT_LINUX.md

Guide de déploiement - Formation Manager Itinova sur serveur Linux

Vue d'ensemble

Ce guide vous accompagne dans le déploiement de l'application Formation Manager Itinova sur un serveur Linux (Ubuntu/Debian) avec authentification locale email/mot de passe (sans OAuth Manus).

Durée estimée : 1-2 heures
Niveau : Intermédiaire

---

Prérequis

Logiciels requis

• Système : Ubuntu 22.04 LTS ou Debian 11+
• Node.js : Version 22.x
• pnpm : Version 10.x
• MySQL : Version 8.0+ ou MariaDB 10.6+
• Nginx : Pour le reverse proxy (optionnel mais recommandé)

Accès nécessaires

• Accès SSH au serveur
• Droits sudo
• Accès à la base de données MySQL

---

Étape 1 : Préparation du serveur

1.1 Mise à jour du système

sudo apt update
sudo apt upgrade -y

1.2 Installation de Node.js 22.x

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

# Vérifier l'installation
node --version  # Doit afficher v22.x.x

1.3 Installation de pnpm

npm install -g pnpm
pnpm --version  # Doit afficher 10.x.x

1.4 Installation de MySQL

sudo apt install -y mysql-server
sudo mysql_secure_installation

---

Étape 2 : Configuration de la base de données

2.1 Créer la base de données et l'utilisateur

sudo mysql

Dans MySQL :

CREATE DATABASE formation_manager CHARACTER SET utf8mb4 COLLATE utf8mb4_unicode_ci;
CREATE USER 'formation_user'@'localhost' IDENTIFIED BY 'VOTRE_MOT_DE_PASSE_SECURISE';
GRANT ALL PRIVILEGES ON formation_manager.* TO 'formation_user'@'localhost';
FLUSH PRIVILEGES;
EXIT;

2.2 Tester la connexion

mysql -u formation_user -p formation_manager
# Entrez le mot de passe, puis EXIT

---

Étape 3 : Déploiement de l'application

3.1 Créer le répertoire de l'application

sudo mkdir -p /var/www/formation-manager-itinova
sudo chown -R $USER:$USER /var/www/formation-manager-itinova
cd /var/www/formation-manager-itinova

3.2 Cloner ou copier les fichiers

Option A : Via Git (recommandé)

git clone https://github.com/votre-repo/formation-manager-itinova.git .

Option B : Via upload manuel

Transférez les fichiers via SCP/SFTP vers /var/www/formation-manager-itinova/

3.3 Installer les dépendances

cd /var/www/formation-manager-itinova
pnpm install

---

Étape 4 : Configuration de l'application

4.1 Créer le fichier .env

nano /var/www/formation-manager-itinova/.env

Contenu du fichier .env :

# Base de données
DATABASE_URL=mysql://formation_user:VOTRE_MOT_DE_PASSE@localhost:3306/formation_manager

# Sécurité JWT (générez une chaîne aléatoire longue)
JWT_SECRET=CHANGEZ_CECI_PAR_UNE_CHAINE_ALEATOIRE_TRES_LONGUE_ET_SECURISEE

# Configuration de l'application
NODE_ENV=production
VITE_APP_TITLE=Formation Manager Itinova
VITE_APP_LOGO=/logo.svg

# Email (optionnel - pour Resend)
RESEND_API_KEY=
RESEND_FROM_EMAIL=

# Port de l'application (par défaut 3000)
PORT=3000

Générer un JWT_SECRET sécurisé :

openssl rand -base64 64

Copiez le résultat dans JWT_SECRET.

4.2 Sécuriser le fichier .env

chmod 600 /var/www/formation-manager-itinova/.env

4.3 Initialiser la base de données

cd /var/www/formation-manager-itinova
pnpm db:push

Cette commande va créer toutes les tables nécessaires.

---

Étape 5 : Compilation de l'application

5.1 Compiler le frontend et le backend

cd /var/www/formation-manager-itinova
pnpm build

5.2 Vérifier que la compilation a réussi

ls -la /var/www/formation-manager-itinova/dist/

Vous devriez voir un fichier index.js.

---

Étape 6 : Configuration du service systemd

6.1 Créer le fichier de service

sudo nano /etc/systemd/system/formation-manager.service

Contenu du fichier :

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

[Service]
Type=simple
User=www-data
WorkingDirectory=/var/www/formation-manager-itinova
Environment="NODE_ENV=production"
Environment="HOME=/var/www/formation-manager-itinova"
Environment="PNPM_HOME=/var/www/formation-manager-itinova/.pnpm"
EnvironmentFile=/var/www/formation-manager-itinova/.env
ExecStart=/usr/bin/pnpm start
Restart=always
RestartSec=10
StandardOutput=journal
StandardError=journal

[Install]
WantedBy=multi-user.target

6.2 Configurer les permissions

sudo chown -R www-data:www-data /var/www/formation-manager-itinova
sudo mkdir -p /var/www/.local/share/pnpm
sudo chown -R www-data:www-data /var/www/.local

6.3 Activer et démarrer le service

sudo systemctl daemon-reload
sudo systemctl enable formation-manager
sudo systemctl start formation-manager

6.4 Vérifier le statut

sudo systemctl status formation-manager

6.5 Voir les logs

sudo journalctl -u formation-manager -f

---

Étape 7 : Configuration de Nginx (optionnel mais recommandé)

7.1 Installer Nginx

sudo apt install -y nginx

7.2 Créer la configuration du site

sudo nano /etc/nginx/sites-available/formation-manager

Contenu du fichier :

server {
    listen 80;
    server_name votre-domaine.com;  # Changez par votre domaine

    # Logs
    access_log /var/log/nginx/formation-manager-access.log;
    error_log /var/log/nginx/formation-manager-error.log;

    # Proxy vers l'application Node.js
    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;
    }
}

7.3 Activer le site

sudo ln -s /etc/nginx/sites-available/formation-manager /etc/nginx/sites-enabled/
sudo nginx -t
sudo systemctl restart nginx

7.4 Configurer le pare-feu

sudo ufw allow 'Nginx Full'
sudo ufw allow OpenSSH
sudo ufw enable

---

Étape 8 : Configuration HTTPS avec Let's Encrypt (recommandé)

8.1 Installer Certbot

sudo apt install -y certbot python3-certbot-nginx

8.2 Obtenir un certificat SSL

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

Suivez les instructions à l'écran.

8.3 Renouvellement automatique

sudo systemctl status certbot.timer

Le renouvellement est automatique.

---

Étape 9 : Créer le premier utilisateur administrateur

9.1 Se connecter à MySQL

mysql -u formation_user -p formation_manager

9.2 Créer un utilisateur admin

-- Générer un hash bcrypt pour le mot de passe "admin123" (à changer immédiatement)
-- Hash bcrypt de "admin123" : $2b$10$rKZhVJQX7mEWQxGqF8vQZOQxqxqxqxqxqxqxqxqxqxqxqxqxqxqxq

INSERT INTO users (email, password, name, role, emailVerified, isActive, createdAt, updatedAt, lastSignedIn)
VALUES (
    'admin@itinova.org',
    '$2b$10$N9qo8uLOickgx2ZMRZoMye7FRNv8va91kpMQH6.OfzrcBizxDbvSK',  -- Mot de passe: admin123
    'Administrateur',
    'admin',
    TRUE,
    TRUE,
    NOW(),
    NOW(),
    NOW()
);

EXIT;

⚠️ IMPORTANT : Changez le mot de passe immédiatement après la première connexion !

---

Étape 10 : Vérification et tests

10.1 Accéder à l'application

Ouvrez votre navigateur et accédez à :

• HTTP : http://votre-domaine.com
• HTTPS : https://votre-domaine.com

10.2 Se connecter

• Email : admin@itinova.org
• Mot de passe : admin123

10.3 Changer le mot de passe

1. Connectez-vous
2. Allez dans "Utilisateurs"
3. Modifiez votre profil
4. Changez le mot de passe

---

Maintenance

Voir les logs

sudo journalctl -u formation-manager -f

Redémarrer l'application

sudo systemctl restart formation-manager

Mettre à jour l'application

cd /var/www/formation-manager-itinova
git pull  # Si vous utilisez Git
pnpm install
pnpm build
sudo systemctl restart formation-manager

Sauvegarder la base de données

mysqldump -u formation_user -p formation_manager > backup_$(date +%Y%m%d_%H%M%S).sql

Restaurer la base de données

mysql -u formation_user -p formation_manager < backup_YYYYMMDD_HHMMSS.sql

---

Dépannage

L'application ne démarre pas

1. Vérifier les logs :

   sudo journalctl -u formation-manager -n 100 --no-pager
   

2. Vérifier que le fichier .env existe et est correct :

   cat /var/www/formation-manager-itinova/.env
   

3. Vérifier que la base de données est accessible :

   mysql -u formation_user -p formation_manager
   

Erreur de permissions

sudo chown -R www-data:www-data /var/www/formation-manager-itinova
sudo mkdir -p /var/www/.local/share/pnpm
sudo chown -R www-data:www-data /var/www/.local

Erreur "drizzle-kit: not found"

cd /var/www/formation-manager-itinova
pnpm install

Port 3000 déjà utilisé

Modifiez le port dans .env :

PORT=3001

Puis redémarrez :

sudo systemctl restart formation-manager

---

Sécurité

Recommandations

1. Changez immédiatement le mot de passe admin par défaut
2. Utilisez HTTPS (Let's Encrypt gratuit)
3. Configurez un pare-feu (ufw)
4. Mettez à jour régulièrement le système et l'application
5. Sauvegardez régulièrement la base de données
6. Limitez l'accès SSH (clés SSH, désactiver root login)
7. Surveillez les logs régulièrement

Sauvegardes automatiques

Créez un script de sauvegarde :

sudo nano /usr/local/bin/backup-formation-manager.sh

Contenu :

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

mkdir -p $BACKUP_DIR

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

# Compresser
gzip $BACKUP_DIR/db_$DATE.sql

# Garder seulement les 30 derniers jours
find $BACKUP_DIR -name "db_*.sql.gz" -mtime +30 -delete

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

Rendre exécutable :

sudo chmod +x /usr/local/bin/backup-formation-manager.sh

Ajouter au cron (tous les jours à 2h du matin) :

sudo crontab -e

Ajouter :

0 2 * * * /usr/local/bin/backup-formation-manager.sh >> /var/log/backup-formation-manager.log 2>&1

---

Support

Pour toute question ou problème :

1. Consultez les logs : sudo journalctl -u formation-manager -f
2. Vérifiez la documentation : /var/www/formation-manager-itinova/README.md
3. Contactez le support technique

---

Annexe : Commandes utiles

# Statut du service
sudo systemctl status formation-manager

# Démarrer le service
sudo systemctl start formation-manager

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

# Redémarrer le service
sudo systemctl restart formation-manager

# Voir les logs en temps réel
sudo journalctl -u formation-manager -f

# Voir les 100 dernières lignes de logs
sudo journalctl -u formation-manager -n 100 --no-pager

# Tester la connexion à la base de données
mysql -u formation_user -p formation_manager

# Vérifier la configuration Nginx
sudo nginx -t

# Recharger Nginx
sudo systemctl reload nginx

# Vérifier l'utilisation des ressources
htop

# Vérifier l'espace disque
df -h

# Vérifier les processus Node.js
ps aux | grep node

---

Fin du guide de déploiement