ficheagent/DEPLOYMENT.md

Guide de Déploiement - Fiche Agent

Ce document décrit la procédure pas à pas pour déployer l'application Fiche Agent sur un serveur de test (Linux Ubuntu/Debian recommandé).

1. Prérequis Serveur

Assurez-vous que votre serveur dispose des dépendances suivantes :

• OS : Ubuntu 22.04 / 24.04 ou Debian 11/12
• Serveur Web : Nginx (recommandé) ou Apache
• PHP : Version 8.2 ou supérieure
  • Extensions requises : bcmath, ctype, fileinfo, json, mbstring, pdo_mysql, tokenizer, xml, zip, gd (pour les PDF/Images), intl.
• Base de données : MySQL 8.0+ ou MariaDB 10.6+
• Composer : Gestionnaire de dépendances PHP
• Node.js & NPM : Version 18+ ou 20+ (pour compiler les assets Vue.js)
• Git : Pour récupérer le code

2. Préparation du système (Exemple Ubuntu/Debian)

Mettez à jour les paquets et installez les dépendances :

# Mise à jour
sudo apt update && sudo apt upgrade -y

# Installation de Nginx, Git, Zip, Unzip, Curl
sudo apt install -y nginx git zip unzip curl

# Installation de PHP 8.2 et des extensions
sudo apt install -y php8.2 php8.2-fpm php8.2-mysql php8.2-mbstring php8.2-xml php8.2-bcmath php8.2-curl php8.2-zip php8.2-intl php8.2-gd

# Installation de Composer
curl -sS https://getcomposer.org/installer | php
sudo mv composer.phar /usr/local/bin/composer

# Installation de Node.js (via NodeSource)
curl -fsSL https://deb.nodesource.com/setup_20.x | sudo -E bash -
sudo apt install -y nodejs

3. Configuration de la Base de Données

Connectez-vous à MySQL/MariaDB et créez la base de données :

# Connexion
sudo mysql -u root -p

# Commandes SQL
CREATE DATABASE fiche_agent CHARACTER SET utf8mb4 COLLATE utf8mb4_unicode_ci;
CREATE USER 'fiche_agent_user'@'localhost' IDENTIFIED BY 'votre_mot_de_passe_securise';
GRANT ALL PRIVILEGES ON fiche_agent.* TO 'fiche_agent_user'@'localhost';
FLUSH PRIVILEGES;
EXIT;

4. Installation de l'Application

4.1 Récupération du Code

Naviguez vers le répertoire web (ex: /var/www) et clonez le dépôt :

cd /var/www
sudo git clone <votre-url-git-repository> fiche-agent
# OU transférez les fichiers via SFTP si vous n'avez pas de dépôt git distant

4.2 Permissions

Assurez-vous que l'utilisateur du serveur web (souvent www-data) est propriétaire des fichiers, et donnez les droits d'écriture aux dossiers de stockage :

cd /var/www/fiche-agent
sudo chown -R www-data:www-data .
sudo chmod -R 775 storage bootstrap/cache

4.3 Installation des Dépendances PHP

Installez les dépendances en mode production :

composer install --optimize-autoloader --no-dev

4.4 Configuration de l'Environnement

Copiez le fichier d'exemple et configurez-le :

cp .env.example .env
nano .env

Modifiez les lignes suivantes dans le fichier .env :

APP_NAME="Fiche Agent"
APP_ENV=production
APP_DEBUG=false
APP_URL=http://votre-domaine-ou-ip.com

DB_CONNECTION=mysql
DB_HOST=127.0.0.1
DB_PORT=3306
DB_DATABASE=fiche_agent
DB_USERNAME=fiche_agent_user
DB_PASSWORD=votre_mot_de_passe_securise

QUEUE_CONNECTION=database

Générez la clé d'application :

php artisan key:generate

4.5 Base de Données & Migrations

Lancez les migrations pour créer les tables :

php artisan migrate --force

(Optionnel) Si vous voulez des données de test initiales :

php artisan db:seed --force

5. Compilation des Assets (Frontend)

Installez les dépendances JS et compilez pour la production :

npm install
npm run build

6. Configuration du Serveur Web (Nginx)

Créez un fichier de configuration Nginx :

sudo nano /etc/nginx/sites-available/fiche-agent

Contenu suggéré :

server {
    listen 80;
    server_name votre-domaine-ou-ip.com;
    root /var/www/fiche-agent/public;

    add_header X-Frame-Options "SAMEORIGIN";
    add_header X-Content-Type-Options "nosniff";

    index index.php;

    charset utf-8;

    location / {
        try_files $uri $uri/ /index.php?$query_string;
    }

    location = /favicon.ico { access_log off; log_not_found off; }
    location = /robots.txt  { access_log off; log_not_found off; }

    error_page 404 /index.php;

    location ~ \.php$ {
        fastcgi_pass unix:/var/run/php/php8.2-fpm.sock;
        fastcgi_param SCRIPT_FILENAME $realpath_root$fastcgi_script_name;
        include fastcgi_params;
    }

    location ~ /\.(?!well-known).* {
        deny all;
    }
}

Activez le site et relancez Nginx :

sudo ln -s /etc/nginx/sites-available/fiche-agent /etc/nginx/sites-enabled/
sudo nginx -t
sudo systemctl reload nginx

7. Configuration des Queues (Supervisor)

Pour que l'envoi d'emails et la génération de PDF fonctionnent en arrière-plan, configurez Supervisor.

Installez Supervisor :

sudo apt install -y supervisor

Créez un fichier de configuration :

sudo nano /etc/supervisor/conf.d/fiche-agent-worker.conf

Contenu :

[program:fiche-agent-worker]
process_name=%(program_name)s_%(process_num)02d
command=php /var/www/fiche-agent/artisan queue:work database --sleep=3 --tries=3 --max-time=3600
autostart=true
autorestart=true
stopasgroup=true
killasgroup=true
user=www-data
numprocs=2
redirect_stderr=true
stdout_logfile=/var/www/fiche-agent/storage/logs/worker.log
stopwaitsecs=3600

Activez Supervisor :

sudo supervisorctl reread
sudo supervisorctl update
sudo supervisorctl start fiche-agent-worker:*

8. Finalisation

Votre application devrait être accessible via l'URL configurée.

Commandes utiles pour la maintenance

• Mettre à jour l'application :

  cd /var/www/fiche-agent
  git pull origin main
  composer install --optimize-autoloader --no-dev
  php artisan migrate --force
  npm run build
  php artisan cache:clear
  php artisan config:cache
  php artisan route:cache
  php artisan view:cache
  supervisorctl restart fiche-agent-worker:*
  

• Vérifier les logs :

  • Laravel : tail -f storage/logs/laravel.log
  • Worker : tail -f storage/logs/worker.log
  • Nginx : /var/log/nginx/error.log