(Guide pratique pour les équipes qui veulent intégrer la suite ERP‑CRM Dolibarr à leur plateforme CMI tout en préservant la continuité de leurs systèmes en place)
TL;DR – Installez Dolibarr en mode modulaire, encapsulez‑le dans un conteneur Docker ou une VM, migrez les données via des API REST, et déployez‑le en mode « shadow » avant la bascule définitive. Un processus CI/CD automatisé garantit que chaque étape s’exécute sans interrompre les services en cours.
1. Contexte et enjeux
| Élément | Description | Contraintes |
|---|---|---|
| Dolibarr | ERP/CRM open‑source très modulaire, écrit en PHP/MySQL (ou MariaDB). | Nécessité d’une intégration fluide avec les processus métiers déjà en place (ex. facturation, stocks). |
| CMI | Plateforme propriétaire ou interne de gestion de Customer‑Management‑Interface (interface client, tickets, historiques). | Environnement déjà en production, bases de données, flux de données et API déjà exposés. |
| Objectif | Ajouter les modules Dolibarr (achat, ventes, stocks…) à la CMI sans interrompre les services existants. | Continuité d’ attività, traçabilité, rollback possible. |
2. Principes de « distribution sans casser l’existant »
-
Isolation fonctionnelle
- Conteneurisation : Utilisez Docker (ou Podman) pour encapsuler Dolibarr.
- Réseaux virtuels : Créez un réseau dédié (
dolibarr-net) qui ne sera exposé qu’au load‑balancer de la CMI.
-
Approche incrémentale
- Mode « shadow » : Déployez d’abord Dolibarr en lecture‑seule (API uniquement).
- Double‑écriture : Replication temporaire des writes vers l’ancien système jusqu’à la migration complète.
-
API‑First & versioning
- Toutes les nouvelles fonctionnalités sont exposées via des points d’exposition REST (
/api/v1/*). - Le client CMI continue d’appeler les API versionnées de l’ancien système ; les nouveaux endpoints sont ajoutés parallèlement.
- Toutes les nouvelles fonctionnalités sont exposées via des points d’exposition REST (
-
Gestion des données
- Export/Import : Utilisez les capacités d’export CSV/JSON de Dolibarr ou les API REST pour extraire les données existantes. – Migrations : scripts Flyway/Liquibase qui appliquent les changements de schéma uniquement après validation.
- CI/CD automatisé
- Pipeline :
build→ image Dockerdolibarr:latest.test→ Scénarios d’intégration (API, performance, sécurité).deploy→ Helm/K8s ou script Ansible sur le serveur de staging.
- Rollback : Tag Docker précédent et bascule du service via un
helm rollbackoudocker-compose up -d <old-image>.
- Pipeline :
3. Étapes détaillées de mise en place
3.1. Pré‑requis techniques
# 1. Docker Engine + Compose
apt-get update && apt-get install -y docker.io docker-compose
# 2. Git pour récupérer les sources
git clone https://github.com/Dolibarr/dolibarr.git /opt/dolibarr-src
# 3. Base de données source (MySQL/MariaDB) déjà en place
# - Hôte : db-prod.example.com
# - User : dolibarr_user
# - Password : ********3.2. Construction de l’image Docker « modulaire »
# Dockerfile.dolibarr
FROM php:8.2-apache
# Packages requis
RUN apt-get update && apt-get install -y \
libpq-dev libsqlite3-dev libzip-dev unzip \
&& docker-php-ext-install -j$(nproc) pgsql pdo_mysql zip \
&& a2enmod rewrite
# Copie du code sourceCOPY --chown=www-data:www-data dolibarr-src/ /var/www/html/
# Installation des dépendances Composer (si nécessaires)
RUN curl -sS https://getcomposer.org/installer | php -- --install-dir=/usr/local/bin -- filename=composer \
&& composer install --no-dev --optimize-autoloader
# Configuration Apache
COPYapache-site.conf /etc/apache2/sites-available/000-dolibarr.conf
RUN a2ensite 000-dolibarr.conf && a2dissite 000-default.conf
EXPOSE 80
ENV DOLIBARR_INSTALL_SERVER_PORT=80```
> **Astuce** : Enveloppez cette image dans un registre privé (Harbor, GitHub Packages) afin de garantir une version *immuable* pour chaque déploiement.
### 3.3. Déploiement en mode « shadow »
```yaml
# docker-compose.override.yml (mode shadow)
version: "3.8"
services:
dolibarr:
image: registry.mycompany.com/dolibarr:shadow-2025-11-03
container_name: dolibarr_shadow
networks:
- dolibarr-net
ports:
- "8082:80" # accessible uniquement en interne, pas du public
environment:
- DB_SERVER=db-prod.example.com - DB_USER=dolibarr_user - DB_PASS=**********
- DOLIBARR_DSN=pdo:mysql://dolibarr_user:********@db-prod.example.com/dolibarr depends_on:
- db-prod restart: unless-stopped
networks:
dolibarr-net:
driver: bridge- Accès : Le service est exposé sur le port interne
8082mais non publié sur le LB public. - Synchronisation : Un job cron (ou un webhook) déclenche une double‑écriture vers le système legacy chaque 5 minutes pour les tables vente, facture, client.
3.4. Migration progressive des données
- Export des tables critiques (clients, articles, historiques) via
SELECT ... INTO OUTFILE. - Import dans la base de Dolibarr en mode lecture‑seule (
read_onlyflag). - Validation : comparer le nombre de lignes et les checksum (
MD5(CONCAT_WS('-', col1, col2…))). - Activer l’écriture : désactiver le mode read‑only et lancer le script sync‑writes :
#!/bin/bash
while true; do
# récupère les nouvelles écritures depuis la CMI (via API)
curl -s http://cmi.internal/api/v1/writes?since=$(date -d "5 minutes ago" +%s) \
| jq -c '.[]' | while read -r line; do
# transforme le payload en requête INSERT dans Dolibarr
php /var/www/html/dolibarr/scripts/sync_write.php "$line"
done
sleep 300
done3.5. Test d’intégration
- Scénarios automatisés (JMeter, Postman) couvrant :
- Création d’une commande dans CMI → apparition dans Dolibarr. – Téléchargement d’un devis → génération du PDF.
- Mise à jour du stock → déclenchement d’un event sur la CMI.
3.6. Bascule finale (go‑live)
| Étape | Action | Rollback |
|---|---|---|
| 1 | Mettre le service dolibarr_shadow en production (port 80 exposé via LB). |
Ancien service maintenu. |
| 2 | Rediriger le trafic CMI vers le nouveau endpoint /api/v1/dolibarr/*. |
Redirection revertible. |
| 3 | Désactiver le double‑écriture après validation des KPI (latence < 200 ms, taux d’erreur < 0,1 %). | Re‑activer l’ancien endpoint. |
| 4 | Supprimer l’image shadow et nettoyer les volumes temporaires. |
– |
4. Bonnes pratiques spécifiques à l’écosystème Dolibarr + CMI
| Pratique | Pourquoi | Mise en œuvre |
|---|---|---|
Utiliser le front controller de Dolibarr (index.php) comme unique point d’entrée |
Permet de centraliser le routing des API et d’ajouter des règles de sécurité. | Créer un .htaccess qui redirige /cmi/api/* vers /dolibarr/index.php. |
| Définir des hooks PHP pour synchroniser les événements CMI | Évite les écritures multiples et garantit la consistance. | hooks/pages/customers.php → écoute afterInsertPayment. |
Versionner les API (/api/v1/...) et déprécier les anciens endpoints lentement |
Les clients existants ne sont pas interrompus. | Documenter les changements dans un changelog OpenAPI et publier un deprecation notice 90 jours avant la suppression. |
| Sauvegarder la base avant chaque migration | Point de restauration immédiat. | mysqldump -h db-prod -u dolibarr_user -p****** dolibarr > /backups/dolibarr_$(date +%F).sql. |
| Surveiller les temps de réponse | Une dégradation peut bloquer le canal CMI. | Prometheus + Grafana : métriques http_request_duration_seconds et error_rate. |
| Sécuriser les communications | Éviter les fuites de données sensibles. | TLS mutualisé : certificats client côté CMI et serveur côté Dolibarr. |
5. Exemple de diagramme de flux (simplifié)
+-------------------+ +--------------------------+ +-------------------+
| CMI (front) | HTTP | Load‑Balancer (L7) | HTTP | Dolibarr (API) |
| /api/v1/... +--------->| (expose /dolibarr/* ) +--------->| /index.php |
+-------------------+ +--------------------------+ +-------------------+
^ | ^ |
| | | double‑écriture (async) |
| (ticket, facturation) | | |
| v v v
Base Legacy DB Legacy DB Dolibarr
(MySQL/Postgres) (exploitation) (nouvelle)- Flèche principale : trafic client → LB → nouveau endpoint Dolibarr.
- Flèche secondaire : mise à jour en temps réel des tables en双向 synchronisation (via webhook ou job cron).
6. FAQ rapide
| Question | Réponse |
|---|---|
| Puis‑je déployer Dolibarr sans Docker ? | Oui, via une installation bare‑metal (PHP‑FPM + Apache/Nginx). Mais le container simplifie l’isolation et la réplication. |
| Quel est le coût d’une migration massive (ex. 2 M de lignes) | Principalement le temps de parallelisation : avec mysqldump + pv on atteint ~10 k lignes/s. Un job nocturne de 4 h suffit généralement. |
| Et si je veux rester sur MySQL 5.7 (legacy) ? | Dolibarr 23+ supporte MySQL 5.6 et 5.7. Il suffit de conserver ce moteur dans le conteneur et de ne pas activer les nouvelles fonctions SQL. |
| Puis‑je garder les parametrages de sécurité CMI ? | Absolument : tous les headers, JWT et tokens sont transmis inchangés au conteneur via le LB. Aucun changement de configuration côté CMI n’est requis. |
| Quel niveau de disponibilité faut‑il viser ? | 99,9 % est réalisable avec un dual‑stack (shadow + prod) pendant la période de transition, puis bascule sur le seul service Dolibarr. |
7. Conclusion
Intégrer Dolibarr à une plateforme CMI sans rompre le fonctionnement actuel repose sur trois piliers :
- Isolation & conteneurisation → aucune interférence avec l’infrastructure existante.
- Déploiement incrémental (shadow + double‑écriture) → migration sans perte de donnée et possibilité de rollback instantané.
- Automatisation CI/CD & monitoring → visibilité totale et capacité de rétablir rapidement le service en cas d’anomalie.
En suivant le plan détaillé ci‑dessus – de la création de l’image Docker à la bascule finale – vous pouvez profiter de la richesse fonctionnelle de Dolibarr (achat, ventes, stocks, relances clients…) tout en conservant la stabilité de votre système CMI actuel.
À vous de jouer : démarrez par le déploiement d’un prototype shadow sur votre environnement de test, validez les flux de synchronisation, puis planifiez la migration progressive en Production. Les bénéfices en termes d’agilité, de reporting et de réduction des coûts de licence seront rapidement perceptibles.
— Bonne intégration ! 🚀