Dolibarr avancé : maintenance sans casser l’existant

Dolibarr avancé : maintenance sans casser l’existant
Comment évoluer votre solution ERP/CRM sans perdre vos données ni vos personnalisations

1. Introduction

Dolibarr est un ERP / CRM open‑source très apprécié pour sa simplicité d’utilisation, son extensibilité et son architecture modulaire.
Dans les entreprises, on le déploie souvent après plusieurs années d’utilisation, avec :

des personnalisations (modules créés ou modifiés) ;

des données historiques (clients, factures, stocks, projets…) ;

des intégrations avec d’autres systèmes (mail, comptabilité, PDG, etc.).

Passer d’une version à une autre (ou migrer le serveur) devient alors un vrai défi : il faut maintenir la continuité du service tout en bénéficiant des nouvelles fonctionnalités et des correctifs de sécurité.

Cet article montre, étape par étape, comment aborder la maintenance avancée de Dolibarr sans casser l’existant, en usant de bonnes pratiques de lifecycle logiciel, de tests et d’automatisation.

2. Principes de base d’une maintenance « sans casse »

Principe	Description	Impact sur Dolibarr
Sauvegarde systématique	Export complet (BDD + fichiers) avant toute opération de changement.	Permet de restaurer en 5 min en cas d’échec.
Isolation des modifications	Utilisation d’un environnement de test ou de branche Git pour les développements.	Aucun risque d’impact sur la production.
Versionnage et CI/CD	Contrôle des scripts de migration, des modules et des configs via Git.	Reproductibilité, traçabilité, rollback automatisé.
Monitoring & Logging	Vérification des logs, alertes sur les erreurs de requêtes SQL.	Détection précoce des ruptures.
Documentation précise	Guide d’installation/migration, checklist de vérifications post‑déploiement.	Réduction des erreurs humaines, transmission du savoir.

3. Architecture de mise à jour recommandée

┌─────────────────┐          ┌─────────────────────┐

│  Production     │          │  Environnement Test │

│ (Dolibarr 9.x)  │◀───────▶ │ (Dolibarr 9.x)      │

└───────▲─────────┘          └───────▲─────────────┘

        │                              │

  (Backup automatisé)               │

        │                              │

┌───────▼─────────┐            ┌───────▼─────────┐

│  Gestion des   │            │  Déploiement   │

│  versions      │            │  automatisé    │

│  (Git, Docker) │            │  (Ansible/CI)  │

└─────────────────┘            └─────────────────┘

3.1 Branche Git pour les développements

master : version en production stable.

dev : branche où vous testez les nouvelles fonctionnalités ou les upgrades.

release/x.y : branches dédiées à chaque version majeure (ex. release/10.0).

Commit policy : chaque modification de module ou de configuration doit être accompagnée d’un patch SQL et d’un test script qui sera exécuté dans l’environnement de test avant d’être fusionnée en master.

3.2 Conteneurisation (Docker)

Container : dolibarr:php8-apache (ou dolibarr:10.0.2).

Volumes : /var/www/html/files, /var/lib/dolibarr/mysql.

Avantages :
- Reproductibilité exacte entre dev, test et prod.
- Possibilité d’utiliser docker‑compose pour créer un cluster de tests (2 × containers web + DB).
- Facilite le rollback à la version de l’image Docker précédente.

4. Étapes concrètes d’une migration sans rupture

4.1 Phase de préparation

Auditer l’existant
- Identifier les modules personnalisés (/custom/, /interfaces/) et leurs dépendances.
- Lister les hooks (ex. plugins hook_certificates, hook_cron) utilisés.

Déterminer le target
- Version cible (ex. Dolibarr 10.0.3).
- Vérifier la matrice de compatibilité (plugins compatibles, champs DB modifiés).

Planifier les fenêtres de maintenance
- Choisir un créneau où l’impact business est minimal.

4.2 Backup complet

# Export de la base

mysqldump -u dolibarr_user -p dolibarr_db > db_backup_$(date +%F).sql
# Copie des fichiers (HTML + attachments)

tar czf files_backup_$(date +%F).tar.gz /var/www/html/files

Conservez les deux fichiers sur un stockage hors‑site (NAS, S3, etc.).

4.3 Installation d’un environnement de test

# docker‑compose.test.yml

version: "3.8"

services:

  db:

    image: mysql:8

    environment:

      MYSQL_DATABASE: dolibarr_db

      MYSQL_USER: dolibarr_user

      MYSQL_PASSWORD: secret

    volumes:

      - db_data:/var/lib/mysql

  php:

    image: dolibarr:10.0.2

    ports:

      - "8080:80"

    volumes:

      - ./files:/var/www/html/files

      - ./custom:/var/www/html/custom

    depends_on:

      - db

volumes:

  db_data:

Lancez :docker compose -f docker‑compose.test.yml up -d.

Migrate la BDD :

docker exec -it <php_container> php -r "require('__doinclude__/main.inc.php');$db->query('SET NAMES utf8');";

Reprenez vos scripts de migration (voir 4.5).

4.4 Migration de la base (procédure «  zéro‑downtime »)

Étape	Action	Pourquoi
a	Créez une vue ou copie de la BDD en test (`CREATE DATABASE dolibarr_test_clone;`).	Garantit l’intégrité de la source de prod.
b	Exécutez le script de migration en transaction (`START TRANSACTION; … COMMIT;`).	Si une erreur survient, vous pouvez `ROLLBACK`.
c	Vérifiez les contraintes : – Existence de nouvelles tables (`hooks`, `llx_categorie`). – Valeur des champs modifiés.	Évite les ruptures de schéma.
d	Testez chaque module (ex. Paiement Stripe, Gestion des devis) via les scénarios de test automatisés (behat, unit‑tests).	Confirmation fonctionnelle avant passage en prod.
e	Si tout est ok, planifiez le basculement (voir 4.6).	Transition contrôlée.

Exemple de script de migration (en SQL)

-- 1. Ajout d'une colonne compatible 10.0

ALTER TABLE llx_demo ADD COLUMN new_field VARCHAR(255) NULL;
-- 2. Migration d'un champ technique

UPDATE llx_critere SET label = REPLACE(label,'V1','V2') WHERE idcriteria=23;
-- 3. Mise à jour d'une valeur de configuration

UPDATE llx_conf SET value='10.0.3' WHERE name='product_version';

Bon à savoir : Depuis Dolibarr 10, les tables utilisent le suffixe llx_. Si vous avez des tables anciennes (catalog, product), pensez à les renommer ou à ajouter le préfixe.

4.5 Validation automatisée

Scénario Behat (BDD) :

Feature: Migration aux nouvelles versions

Scenario: Vérifier l'affichage du catalogue après migration

  Given I am on the "/index.php?module=products" page

  When I click "Add a product"

  Then I should see the product creation form

Tests unitaires (PHPUnit) pour les hooks personnalisés.

Ces suites de tests s’exécutent dans le pipeline CI (GitLab CI, GitHub Actions) à chaque push sur dev.

4.6 Bascule en production (zero‑downtime)

Mise en place du “blue‑green”
- Blue : serveur en cours d’utilisation.
- Green : nouvelle instance (Docker + même BDD) avec la version cible.

Synchronisation des fichiers

rsync -av /var/www/html/files/ blue:/var/www/html/files/

rsync -av /var/www/html/custom/ blue:/var/www/html/custom/

Activation progressive
- Bascule du load‑balancer sur le green pour 5 % du trafic.
- Monitoring → vérification des métriques (latence, erreurs 500).
- Si tout est OK, mise à 100 % du trafic.

Cleanup
- Désactivation et suppression du blue après validation pendant 24 h.

Alternative : Rolling upgrade via Ansible : un serveur à la fois est mis à jour, puis redémarré, pendant que le reste continue de servir.

5. Checklist post‑déploiement

✅	Action	Détails
1	Vérifier les logs (`/var/log/apache2/error.log`, `php-fpm.log`).	Rechercher `ERR` ou `Fatal error`.
2	Tester les requêtes fréquentes (listes de produits, factures, contacts).	Utiliser des scripts “smoke test” qui exécutent des requêtes SQL de contrôle.
3	Re‑regénérer le cache (`php cache.php clean`).	Évite l’affichage d’anciennes données.
4	Valider les cron (`php cron.php` succès).	Les tâches planifiées (ex. génération PDF, envoi d’emails) doivent s’exécuteršu.
5	Contrôler les droits (`chmod 750` sur dossiers, `chown www-data`).	Prévenir les erreurs de permission.
6	Envoyer un rapport d’activité au client / à l’équipe.	Inclure les indicateurs de bascule, les erreurs rencontrées, le temps de maintenance.
7	Planifier le backup suivant (prévoir un point de restauration).	Ne jamais attendre la fin du projet pour refaire un backup complet.

6. Astuces & pièges à éviter

Astuce	Explication
Utiliser toujours l’API interne (`$this->db->query` ou `$this->DL->...`)	évite les appels SQL bruts qui deviennent incompatibles entre versions.
Ne jamais modifier le fichier `core.php`	il est écrasé à chaque upgrade. Préférez les hook ou patch dans `/custom/`.
Tester les champs `txt` qui sont convertis en HTML depuis la version 9.
Vérifier les dates : en 10.x, le type `timestamp` est remplacé par `datetime`; pensez à convertir les champs `date` lors d’une migration.
Les modules gratuits du marketplace (ex. `payseed`, `Invoice consolidate`) peuvent casser la compatibilité ; examinez le `CHANGELOG`.
Nettoyer les tables `llx_password` si vous avez migré vers OAuth2 : des clés orphelines peuvent générer des erreurs d’authentification.
Planifier les mises à jour de la base régulièrement (ex. chaque 2‑3 mois) afin d’éviter les différences majeures entre plusieurs années de versions.
Ne jamais faire de mise à jour directe en prod si vous avez des personnalisations lourdes ; passez toujours par un environnement de test validé.

7. Exemple de workflow complet (GitLab CI)

stages:

  - backup

  - test

  - migrate

  - deploy

  - postcheck
variables:

  DOCKER_IMAGE: "dolibarr:10.0.3"
backup_db:

  stage: backup

  script:

    - mysqldump -h $DB_HOST -u $DB_USER -p$DB_PASSWORD $DB_NAME > backup_$(date +%F).sql
test_migration:

  stage: test

  image: php:8-apache

  services:

    - mysql:8

  script:

    - docker pull $DOCKER_IMAGE

    - docker run -d --name dolibarr-test -p 8080:80 -e MYSQL_HOST=$DB_HOST -e MYSQL_DATABASE=$DB_NAME $DOCKER_IMAGE

    - sleep 10

    - php vendor/autoload.php # installe les dépendances de test

    - ./vendor/bin/phpunit tests/MigrationTest.php

  only:

    - dev
migrate_prod:

  stage: migrate

  image: alpine/k8s

  script:

    - ./scripts/rollback.sh   # point de restauration rapide si besoin

    - ./scripts/migrate.sh    # script décrit en 4.4

    - ./scripts/blue-green.sh # bascule progressive

  only:

    - master

  when: manual

Ce pipeline reproduit exactement les étapes de l’article, tout en laissant la liberté de les adapter à votre contexte (Azure, AWS, serveur bare‑metal…).

8. Conclusion

Mettre à jour Dolibarr sans compromettre vos données ou vos personnalisations n’est pas une opération “au hasard”. En suivant ces bonnes pratiques :

Isoler chaque changement (branches Git, conteneurs Docker).

Sauvegarder de façon fiable avant chaque manipulation.

Tester chaque étape dans un environnement qui reproduit exactement la configuration de prod.

Automatiser les migrations et les contrôles via CI/CD.

Basculer progressivement (blue‑green / rolling upgrade).

vous bénéficiez des dernières corrections de sécurité et des fonctionnalités sans redouter les effets de bord.

Citation clé : “La migration n’est jamais un événement, c’est un processus continu.” – adoptez‑le dans votre gouvernance Dolibarr, et chaque version deviendra une opportunité d’amélioration, non une menace.

Ressources complémentaires

Ressource	Lien
Documentation officielle – Upgrade	https://github.com/Dolibarr/dolibarr/blob/develop/INSTALL.md#upgrade
Docker Hub – Dolibarr images	https://hub.docker.com/r/dolibarr/dolibarr
Plugin Marketplace	https://github.com/Dolibarr/dolibarr-modules-market
Guides de migration 9 → 10 (PDF)	https://github.com/Dolibarr/dolibarr/wiki/Upgrade-9-to-10
Exemple de pipeline CI/CD	https://gitlab.com/dolibarr-ci/dolibarr-migration-pipeline

Bonnes pratiques d’administration Dolibarr—et surtout, veillez toujours à garder vos données en sécurité avant toute transformation.

Dolibarr avancé : maintenance sans casser l’existant

1. Introduction

2. Principes de base d’une maintenance « sans casse »

3. Architecture de mise à jour recommandée

3.1 Branche Git pour les développements

3.2 Conteneurisation (Docker)

4. Étapes concrètes d’une migration sans rupture

4.1 Phase de préparation

4.2 Backup complet

4.3 Installation d’un environnement de test

4.4 Migration de la base (procédure «  zéro‑downtime »)

Exemple de script de migration (en SQL)

4.5 Validation automatisée

4.6 Bascule en production (zero‑downtime)

5. Checklist post‑déploiement

6. Astuces & pièges à éviter

7. Exemple de workflow complet (GitLab CI)

8. Conclusion

Ressources complémentaires

Comment Dolibarr et la gestion commerciale peut-il améliorer votre productivité ?

Comment Dolibarr ERP peut-il améliorer votre productivité ?

Dolibarr en production : tickets et bonnes pratiques avec intégrations modernes

Dolibarr et la gestion de la comptabilité : Les meilleures pratiques à connaître

Dolibarr et la gestion des devis : Astuces et conseils dʼexperts

Comparatif des solutions Dolibarr open source

1. Introduction

2. Principes de base d’une maintenance « sans casse »

3. Architecture de mise à jour recommandée

3.1 Branche Git pour les développements

3.2 Conteneurisation (Docker)

4. Étapes concrètes d’une migration sans rupture

4.1 Phase de préparation

4.2 Backup complet

4.3 Installation d’un environnement de test

4.4 Migration de la base (procédure « zéro‑downtime »)

Exemple de script de migration (en SQL)

4.5 Validation automatisée

4.6 Bascule en production (zero‑downtime)

5. Checklist post‑déploiement

6. Astuces & pièges à éviter

7. Exemple de workflow complet (GitLab CI)

8. Conclusion

Ressources complémentaires

Publications similaires

2. Principes de base d’une maintenance « sans casse »

4.4 Migration de la base (procédure «  zéro‑downtime »)