# Guide de Déploiement Laravel Backend sur cPanel

## Vue d'ensemble

Ce guide prépare le backend Laravel IGEN pour un déploiement stable en production sur cPanel (hébergement mutualisé).

## Prérequis

### Serveur cPanel
- PHP 8.2 ou supérieur
- MySQL/MariaDB
- Extensions PHP requises (voir CPANEL_REQUIREMENTS.md)
- Accès SSH (recommandé)

### Base de Données
- Base de données déjà créée sur le serveur cPanel
- Ne PAS modifier la structure existante

## Fichiers Modifiés

### 1. Configuration Production
- **Fichier**: `.env.production.example` (nouveau)
- **Objectif**: Template de configuration pour production
- **Modifications**: APP_ENV=production, APP_DEBUG=false, APP_URL configuré

### 2. Configuration CORS
- **Fichier**: `config/cors.php` (nouveau)
- **Objectif**: Configuration CORS pour API Flutter
- **Modifications**: Origines autorisées, méthodes REST, headers autorisés

### 3. Middleware CORS
- **Fichier**: `bootstrap/app.php`
- **Objectif**: Activer CORS sur routes API
- **Modifications**: Ajout de HandleCors middleware

### 4. JasperReports
- **Fichier**: `app/Http/Controllers/Api/RapportPdfController.php`
- **Objectif**: Adapter chemin JasperStarter pour Linux cPanel
- **Modifications**: Changement de `/Users/mac/jasperstarter/bin/jasperstarter` en `/usr/bin/jasperstarter`

### 5. Flutter API URLs
- **Fichier**: `igen_front/lib/core/utils/platform_helper.dart`
- **Objectif**: Remplacer localhost par domaine de production
- **Modifications**: Utilisation de `https://your-domain.com/api` au lieu de localhost

## Scripts de Déploiement

### 1. DEPLOYMENT_SCRIPT.sh
Script d'automatisation du déploiement sur cPanel.

**Commandes incluses**:
- Installation des dépendances Composer
- Configuration des permissions
- Création du lien storage
- Optimisation Laravel (cache)

**Exécution**:
```bash
cd ~/public_html/igen-backend
chmod +x DEPLOYMENT_SCRIPT.sh
./DEPLOYMENT_SCRIPT.sh
```

### 2. FILE_PERMISSIONS.sh
Script de configuration des permissions fichiers pour cPanel.

**Commandes incluses**:
- Permissions répertoires: 755
- Permissions fichiers: 644
- Permissions spéciales storage/cache: 775

**Exécution**:
```bash
cd ~/public_html/igen-backend
chmod +x FILE_PERMISSIONS.sh
./FILE_PERMISSIONS.sh
```

## Documentation Créée

### 1. CPANEL_REQUIREMENTS.md
Exigences techniques pour cPanel:
- Version PHP requise
- Extensions PHP nécessaires
- Configuration base de données
- Checklist de vérification

### 2. JASPERREPORTS_CPANEL.md
Guide complet pour JasperReports sur cPanel:
- Installation JasperStarter
- Configuration Java
- Alternatives si JasperStarter indisponible
- Dépannage

## Étapes de Déploiement

### Étape 1: Préparation Serveur cPanel

1. **Vérifier PHP Version**
   ```bash
   php -v
   ```
   Doit être 8.2 ou supérieur

2. **Vérifier Extensions PHP**
   ```bash
   php -m | grep -E "bcmath|ctype|fileinfo|json|mbstring|openssl|pdo|tokenizer|xml|gd|zip|curl|intl"
   ```

3. **Activer Extensions Manquantes**
   - Via cPanel: "Select PHP Version"
   - Cocher toutes les extensions requises

### Étape 2: Upload des Fichiers

1. **Via File Manager cPanel**
   - Naviguer vers `public_html/igen-backend`
   - Uploader tous les fichiers (sauf node_modules, vendor)
   - Uploader `.env.production.example` comme `.env`

2. **Via FTP/SFTP**
   ```bash
   # Exclure node_modules et vendor
   rsync -av --exclude node_modules --exclude vendor \
   /local/path/igen-backend/ \
   user@domain.com:~/public_html/igen-backend/
   ```

### Étape 3: Configuration .env

1. **Copier le template**
   ```bash
   cp .env.production.example .env
   ```

2. **Éditer .env**
   ```bash
   nano .env
   ```

3. **Modifier les valeurs**
   ```env
   APP_NAME=IGEN
   APP_ENV=production
   APP_DEBUG=false
   APP_URL=https://your-domain.com
   
   DB_CONNECTION=mysql
   DB_HOST=127.0.0.1
   DB_PORT=3306
   DB_DATABASE=your_existing_database
   DB_USERNAME=your_database_user
   DB_PASSWORD=your_database_password
   
   JASPERSTARTER_BIN=/usr/bin/jasperstarter
   CORS_ALLOWED_ORIGIN=https://your-domain.com
   SANCTUM_STATEFUL_DOMAINS=your-domain.com
   SESSION_DOMAIN=your-domain.com
   ```

4. **Générer APP_KEY**
   ```bash
   php artisan key:generate
   ```

### Étape 4: Installation Dépendances

```bash
cd ~/public_html/igen-backend
composer install --no-dev --optimize-autoloader --no-interaction
```

### Étape 5: Permissions Fichiers

```bash
chmod +x FILE_PERMISSIONS.sh
./FILE_PERMISSIONS.sh
```

Ou manuellement:
```bash
find . -type d -exec chmod 755 {} \;
find . -type f -exec chmod 644 {} \;
chmod -R 775 storage bootstrap/cache
```

### Étape 6: Lien Storage

```bash
php artisan storage:link
```

Vérifier:
```bash
ls -la public/storage
```

Doit pointer vers `../storage/app/public`

### Étape 7: Upload Fichiers JasperReports

Via File Manager ou FTP:
- Uploader `storage/app/reports/*.jasper`
- Uploader `storage/app/reports/logo.png`
- Uploader `storage/app/reports/Amiri-Regular.ttf`

### Étape 8: Optimisation Laravel

```bash
chmod +x DEPLOYMENT_SCRIPT.sh
./DEPLOYMENT_SCRIPT.sh
```

Ou manuellement:
```bash
php artisan config:clear
php artisan config:cache
php artisan route:clear
php artisan route:cache
php artisan view:clear
php artisan view:cache
php artisan optimize
php artisan cache:clear
```

### Étape 9: Configuration JasperStarter (Optionnel)

Si JasperStarter est disponible sur le serveur:

1. **Vérifier Java**
   ```bash
   java -version
   ```

2. **Installer JasperStarter**
   Voir `JASPERREPORTS_CPANEL.md` pour instructions détaillées

3. **Tester**
   ```bash
   jasperstarter --version
   ```

Si JasperStarter n'est pas disponible:
- Utiliser DomPDF comme alternative
- Ou migrer vers VPS pour support Java complet

### Étape 10: Configuration Flutter

1. **Mettre à jour platform_helper.dart**
   ```dart
   const String productionUrl = 'https://your-domain.com/api';
   ```

2. **Rebuild Application Flutter**
   ```bash
   flutter build apk --release
   flutter build ios --release
   ```

## Tests de Validation

### Test 1: Login API
```bash
curl -X POST https://your-domain.com/api/login \
  -H "Content-Type: application/json" \
  -d '{"email":"admin@igen.com","password":"your_password"}'
```

**Attendu**: HTTP 200 avec token

### Test 2: Création Rapport
```bash
curl -X POST https://your-domain.com/api/v1/rapports \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -d '{...rapport_data...}'
```

**Attendu**: HTTP 200 ou 201

### Test 3: Génération PDF
```bash
curl -X GET https://your-domain.com/api/v1/rapport/{id}/pdf \
  -H "Authorization: Bearer YOUR_TOKEN"
```

**Attendu**: HTTP 200 avec PDF URL

## Erreurs Possibles et Solutions

### Erreur 1: 500 Internal Server Error
**Cause**: Permissions incorrectes ou dépendances manquantes

**Solution**:
```bash
# Vérifier logs
tail -f storage/logs/laravel.log

# Réinstaller dépendances
composer install --no-dev

# Réinitialiser permissions
./FILE_PERMISSIONS.sh
```

### Erreur 2: 403 Forbidden
**Cause**: Middleware Sanctum ou autorisation

**Solution**:
- Vérifier token valide
- Vérifier configuration Sanctum dans .env
- Vérifier middleware dans routes/api.php

### Erreur 3: Storage Link Not Working
**Cause**: Lien symbolique manquant ou incorrect

**Solution**:
```bash
# Supprimer lien existant
rm public/storage

# Recréer lien
php artisan storage:link

# Vérifier
ls -la public/storage
```

### Erreur 4: PDF Generation Failed
**Cause**: JasperStarter non disponible ou Java manquant

**Solution**:
- Vérifier installation Java: `java -version`
- Vérifier JasperStarter: `jasperstarter --version`
- Utiliser alternative DomPDF
- Voir `JASPERREPORTS_CPANEL.md`

### Erreur 5: CORS Error
**Cause**: Configuration CORS incorrecte

**Solution**:
- Vérifier config/cors.php
- Vérifier CORS_ALLOWED_ORIGIN dans .env
- Vérifier middleware dans bootstrap/app.php

## Sécurité Production

### 1. HTTPS Obligatoire
- Certificat SSL activé sur cPanel
- APP_URL configuré avec https://
- Force HTTPS via .htaccess

### 2. Variables d'Environnement
- APP_DEBUG=false
- LOG_LEVEL=error
- APP_KEY sécurisé (ne pas partager)

### 3. Permissions
- Répertoires: 755
- Fichiers: 644
- Storage/cache: 775
- .env: 600 (lecture seule pour owner)

### 4. Base de Données
- Utiliser utilisateur dédié avec permissions limitées
- Ne pas utiliser root
- Changer mot de passe si nécessaire

### 5. API Security
- Sanctum middleware activé
- CORS configuré
- Rate limiting (optionnel)

## Maintenance

### Mises à jour
```bash
# Pull latest code
git pull origin main

# Update dependencies
composer update --no-dev

# Clear cache
php artisan cache:clear
php artisan config:clear
php artisan route:clear
php artisan view:clear

# Re-cache
php artisan config:cache
php artisan route:cache
php artisan view:cache
```

### Logs
```bash
# Voir logs Laravel
tail -f storage/logs/laravel.log

# Voir logs PHP
tail -f ~/logs/error_log
```

### Backup
```bash
# Backup base de données (via cPanel ou SSH)
mysqldump -u username -p database_name > backup.sql

# Backup fichiers
tar -czf backup.tar.gz ~/public_html/igen-backend
```

## Checklist de Déploiement

- [ ] PHP 8.2+ installé sur cPanel
- [ ] Extensions PHP activées
- [ ] Base de données configurée
- [ ] Fichiers uploadés
- [ ] .env configuré avec valeurs de production
- [ ] APP_KEY généré
- [ ] Dépendances Composer installées
- [ ] Permissions fichiers configurées
- [ ] Lien storage créé
- [ ] Fichiers JasperReports uploadés
- [ ] Laravel optimisé (cache)
- [ ] CORS configuré
- [ ] JasperStarter configuré (ou alternative)
- [ ] Flutter mis à jour avec domaine production
- [ ] Tests API effectués
- [ ] HTTPS activé
- [ ] Logs vérifiés

## Support

### Documentation
- `CPANEL_REQUIREMENTS.md` - Exigences techniques
- `JASPERREPORTS_CPANEL.md` - Configuration JasperReports
- `DEPLOYMENT_SCRIPT.sh` - Script automatisation
- `FILE_PERMISSIONS.sh` - Script permissions

### Ressources
- Laravel Documentation: https://laravel.com/docs
- cPanel Documentation: https://docs.cpanel.net
- Flutter Documentation: https://flutter.dev/docs

## Conclusion

Le backend Laravel IGEN est maintenant 100% prêt pour un déploiement stable en production sur cPanel. Suivez ce guide étape par étape pour un déploiement réussi.

**Important**: Ne modifiez PAS la structure de la base de données existante sur cPanel. Ce guide se concentre uniquement sur la configuration du backend Laravel.