Objectif : Vous fournir un cadre complet et réutilisable pour diagnostiquer, tester et dépanner votre instance Dolibarr — tout en gardant votre configuration de production intacte. > Public cible : Administrateurs, développeurs et consultants qui souhaitent mettre en œuvre des correctifs, des migrations ou des évolutions fonctionnelles sans risquer de casser l’existant.
1. IntroductionDolibarr est un ERP/CRM open‑source très répandu, mais comme tout logiciel, il peut cristalliser :
| Problèmes courants | Conséquences potentielles |
|---|---|
| Mise à jour du core sans sauvegarde | Perte de données ou incompatibilité de modèles |
Modifications directes sur la table llx_... |
Corruption de la base ou bugs imprévus |
| Installation de modules tiers non testés | Installation qui plante ou surcharge les hooks |
| Configuration serveur (PHP, MySQL, Apache/Nginx) non adaptée | Erreurs 500, lenteur ou deadlocks |
Le défi consiste à identifier ces dysfonctionnements, à les analyser, puis à proposer une solution sans toucher directement à votre instance de production. Le chemin le plus sûr passe par la création d’un environnement de test répliqué et la mise en place d’une procédure pas à pas documentée.
2. Concepts Clés Avant de Commencer
| Terme | Description |
|---|---|
| Environnement de test (sandbox) | Instance isolée de Dolibarr (DB + fichiers) où vous pouvez appliquer toutes les modifications. |
| Backup (dump) | Export SQL de la base et copie du répertoire htdocs avant chaque intervention. |
| Mode debug | Activation de debug mode dans dolibarr.conf / truc.conf pour obtenir des logs détaillés. |
| Version control (Git) | Stockage de vos scripts de mise à jour, configuration et modules afin de pouvoir revenir en arrière. |
| CI/CD (optionnel) | Pipeline automatisé qui exécute les tests fonctionnels sur chaque changement. |
3. Modèle de Tutoriel Pas à Pas « Sans Casser l’Existing »
Note : Le modèle suivant peut être copié-collé dans votre documentation interne (Confluence, Wiki, etc.) et adapté à chaque nouveau diagnostic.
3.1. Pré‑requis
| ✅ | Action |
|---|---|
| 1 | Accéder aux logs : /var/log/apache2/error.log ou /var/log/nginx/error.log ; activer debug dans Dolibarr configuration → General settings → Debug mode. |
| 2 | Vérifier la version : php -v, mysql --version, apache2 -v ou nginx -v. |
| 3 | Installer les dépendances : composer install (si vous avez des modules externes). |
| 4 | Avoir un espace de sauvegarde au moins de la même taille que votre production. |
3.2. Étape 0 – Création d’un sandbox
# 0.1. Créez un répertoire de travail
mkdir -p /opt/dolibarr-sandbox/{backup,web}
cd /opt/dolibarr-sandbox
# 0.2. Sauvegardez la base (exemple MySQL)
mysqldump -h localhost -u dolibarr_user -p dolibarr_db > backup/dolibarr_db_$(date +%F).sql
# 0.3. Copiez la configuration et le code sourcecp -r /var/www/html/dolibarr/* web/
cp /var/www/html/dolibarr/htdocs/config/dolibarr.conf web/config/
# 0.4. Créez la base de test
mysql -u root -p -e "CREATE DATABASE dolibarr_test CHARACTER SET utf8mb4 COLLATE utf8mb4_unicode_ci;"
mysql -u root -p dolibarr_test < backup/dolibarr_db_$(date +%F).sql```
> **Résultat attendu** : Vous avez maintenant `dolibarr_test` et le répertoire `web` où toutes les modifications seront faites. Aucun impact sur votre serveur de production.
---
### 3.3. Étape 1 – Activation du mode debug
Éditez `web/config/dolibarr.conf` :
```php
$conf['debug'] = 1; // Affiche toutes les notices, warnings
$conf['debugsql'] = 1; // Log des requêtes SQL
$conf['allow_remote_url'] = 1; // Si vous utilisez des libs externesRedémarrez le serveur web (Apache/Nginx) :
systemctl reload apache2 # ou nginx3.4. Étape 2 – Identification du symptôme
| Symptomatique | Action de diagnostic |
|---|---|
| Erreur 500 « Internal Server Error » | Consultez les logs Apache/Nginx + Dolibarr (error_log). |
| Page blanche après mise à jour du core | Comparez les versions version.txt du core vs. votre copie. |
| Modules inconsistants | Vérifiez list of installed modules dans la partie « Gestion » → « Modules ». |
| Timeout lors d’un appel API | Activez le tracing réseau (Wireshark/tcpdump) ou testez avec curl -v. |
3.5. Étape 3 – Analyse de l’erreur (exemple concret)
3.5.1. Exemple d’erreur de base de données
[2025-11-03 14:27:12] PHP Notice: Mysql default collation 'latin1_swedish_ci' is not supported by Dolibarr. Please configure your DB with utf8mb4_unicode_ci.3.5.2. Étapes de résolution en sandbox
-
Vérifier la collation actuelle :
SELECT DEFAULT_COLLATION_NAME FROM INFORMATION_SCHEMA.SCHEMATA WHERE SCHEMA_NAME='dolibarr_test'; -
Re‑créer la base avec la bonne collation :
DROP DATABASE IF EXISTS dolibarr_test;
CREATE DATABASE dolibarr_test CHARACTER SET utf8mb4 COLLATE utf8mb4_unicode_ci;
SOURCE backup/dolibarr_db_2025-11-02.sql; -
Re‑importer le code : redémarrer le sandbox.
- Valider : rafraîchir la page → l’erreur a disparu.
3.6. Étape 4 – Application sécurisée du correctif en production
Principe : ne jamais appliquer directement le correctif sur le serveur de production.
Utilisez le pipeline de déploiement suivant :
| Action | Description |
|---|---|
| 1. Export du patch | Archivez le répertoire patch/ (ex. dolibarr_fix_2025-11-03.tar.gz). |
| 2. Test dans le sandbox | Refaites toutes les étapes 0‑3 avec le patch. |
| 3. Validation fonctionnelle | Exécutez les scénarios de test automatisés (phpunit, selenium). |
| 4. Planification du déploiement | Choisissez une fenêtre de maintenance. |
| 5. Backup final | mysqldump + copie du répertoire htdocs. |
| 6. Rollback plan | Conservez le dump et la version originale du repo Git. |
| 7. Déploiement | git pull / copy files + php bin/console doctrine:updating-schema --force (si besoin). |
| 8. Post‑déploiement | Vérifiez les logs, testez les scénarios critiques, désactivez le debug. |
3.7. Étape 5 – Documentation et suivi| ✔️ | Élément à consigner |
|—|———————-|
| Ticket interne | ID du problème, description, cause racine. |
| Checklist | Étapes reproduites, tests effectués, résultats. |
| Version du patch | v1.2.0‑fix‑collation‑utf8mb4. |
| Date de déploiement | Horodatage + responsable. |
| Vérifications post‑déploiement | Dashboard de monitoring (Uptime, erreurs 500). |
| Retours | Retour du client ou de l’équipe support. |
4. Bonnes Pratiques à Intégrer
| Pratique | Pourquoi | Comment la mettre en œuvre |
|---|---|---|
| Versionner tout (code, config, SQL) | Historique clair, rollback facile | Git + GitHub/GitLab/Bitbucket |
| Utiliser des branchesfeature | Isoler les modifications temporaires | git checkout -b fix/collation-utf8mb4 |
| Test automatisé | Détecter les régressions avant le prod | PHPUnit (unit), Behat (intégration) |
| Sauvegardes incrémentales | Réduire le temps de restauration | mysqldump --single-transaction toutes les heures |
| Limitation des droits | Empêcher les modifications accidentelles | chmod 750 sur htdocs ; chown www-data:www-data |
| Surveiller les logs en temps réel | Détection précoce d’anomalies | tail -f /var/log/apache2/error.log + docker logs si containerisé |
5. Exemple Complet de Script de Diagnostic
#!/bin/bash# ==========================================
# diagnose_dolibarr.sh – script de audit basique
# ==========================================
set -euo pipefail
# 1️⃣ Variables
APP_DIR="/var/www/html/dolibarr"
BACKUP_DIR="/opt/dolibarr-backup/$(date +%F_%H%M)"
DB_NAME="dolibarr_db"
DB_USER="dolibarr_user"
DB_PASS="******"
LOG_FILE="/var/log/apache2/dolibarr_debug.log"
# 2️⃣ Créer backup
mkdir -p "$BACKUP_DIR"
echo "[INFO] Sauvegarde du code dans $BACKUP_DIR"
cp -r "$APP_DIR" "$BACKUP_DIR"
# 3️⃣ Dump base
echo "[INFO] Dump de la base $DB_NAME"
mysqldump -u "$DB_USER" -p"$DB_PASS" "$DB_NAME" > "$BACKUP_DIR/db_$(date +%F).sql"
# 4️⃣ Vérifier PHP version
php_version=$(php -r "echo PHP_VERSION;" )
echo "[INFO] Version PHP : $php_version"
# 5️⃣ Activer le debug
sed -i 's/$conf\['\''debug'\''\];/ $conf['\''debug'\''']; = 1;/' "$APP_DIR/htdocs/config/dolibarr.conf"
sed -i 's/$conf\['\''debugsql'\''\];/ $conf['\''debugsql'\''']; = 1;/' "$APP_DIR/htdocs/config/dolibarr.conf"
# 6️⃣ Reload Apache
systemctl reload apache2
# 7️⃣ Afficher les 20 dernières erreurs
echo "[WARN] ==== Les 20 dernières lignes du log APACHE ==== "
tail -n 20 "$LOG_FILE"
# 8️⃣ Check de la configuration MySQL
mysql -u "$DB_USER" -p"$DB_PASS" -e "SELECT VERSION();"
echo "[INFO] Diagnostic terminé. Backup dans $BACKUP_DIR"Utilisation :
chmod +x diagnose_dolibarr.sh && sudo ./diagnose_dolibarr.sh
6. Conclusion- Diagnostiquer Dolibarr ne doit jamais se faire en production brute ; créez toujours un sandbox isolé.
- Documentez chaque étape sous forme de tutoriel pas à pas : vous gagnerez en reproductibilité et en traçabilité.
- Validez chaque correctif à l’aide d’un pipeline de tests (unitaires, fonctionnels) avant le déploiement.
- Planifiez le rollback dès le départ : un backup complet, un script de restauration et la connaissance du point exact où la version « stable » a été sauvegardée.
En suivant ce modèle, vous disposerez d’une méthode itérative, fiable et sécurisée pour diagnostiquer et corriger Dolibarr tout en préservant l’intégrité de votre environnement de production.
Annexes
| Annexe | Contenu |
|---|---|
| A. Modèle de ticket JIRA | Champs : Summary, Description, Root Cause, Fix Version, Test Plan, Deploy Date. |
B. Exemple de fichier .gitlab-ci.yml |
CI qui lance les tests PHPUnit + Behat sur le sandbox Docker. |
| C. Checklist de validation | 10 points à cocher avant de passer en production. |
| D. Glossaire | ERP, CRM, SQL Collation, Debug Mode, Sandbox. |
À retenir : la clé d’un diagnostic réussi réside dans la séparation claire entre l’environnement de test et la production, ainsi que dans la traçabilité rigoureuse de chaque action. Vous êtes maintenant armé pour aborder les problèmes Dolibarr sans jamais « casser l’existant ». 🚀