Dolibarr en production : web service et bonnes pratiques pour réduire les erreurs

Guide complet pour les équipes IT et les développeurs souhaitant exploiter Dolibarr dans un environnement de production fiable et résilient.

1. Introduction

Dolibarr est un ERP/CRM open source très répandu qui répond à de nombreux besoins métiers : gestion des devis, achats, stocks, factures, abonnements, etc. Sa modularité en fait une solution adaptée aux petites structures comme aux grands groupes. Toutefois, déployer Dolibarr en production nécessite de dépasser le simple « ça marche sur mon poste » : il faut garantir la continuité de service, la sécurité des données et la mintabilité des incidents.

Ce qui suit propose :

  1. Une vue d’ensemble de l’architecture web‑service de Dolibarr.

  2. Des bonnes pratiques (configuration, déploiement, monitoring, sécurité…) pour minimiser les erreurs en production.

  3. Des outils et automatisations qui stabilisent l’application et facilitent le dépannage.

2. Architecture du web‑service Dolibarr

Composant Rôle Technologies typiques
Application PHP Logique métier (CRUD, calculs, workflow) PHP ≥ 7.4 (ou 8.x)
Base de données Persistance des données MySQL/MariaDB ≥ 10.5 ou PostgreSQL ≥ 12
Cache (optionnel) Accélération des requêtes fréquentes APCu, Redis, Memcached
Web server Exécution du PHP et routage HTTP Apache + mod_php / Nginx + PHP‑FPM
Web‑service API Exposition de services REST/SOAP https://your-domain.com/dolibarr/api
CLI (scripts cron) Tâches périodiques (export, nettoyage) PHP + cron

2.1 API native de Dolibarr

  • REST (v3+ depuis Dolibarr 9) : URLs du type /api/wiki.php/{module}?range=...&start=...&limit=...&sort=....

  • SOAP (legacy) : WSDL générés à la volée, utiles si vous avez besoin d’échanger avec des ERP classiques.

Caractéristiques à retenir

Caractéristique Impact sur la stabilité
Stateless Chaque appel doit être auto‑suffisant ; pas de session implicite entre deux requêtes.
Token d’authentification (JWT ou cookie PHPSESSID) Nécessite une gestion rigoureuse des jetons pour éviter les fuites.
Limites de requêtes Implémenter des quotas pour protéger le serveur sous forte charge.
Versionnage Verrouiller la version de l’API (ex. /api/v1/) pour éviter les ruptures inattendues.

3. Bonnes pratiques pour réduire les erreurs en production

3.1 1. Pré‑déploiement : tests automatisés

Action Pourquoi Exemple d’outil
Tests unitaires (PHPUnit) Attrape les bugs avant le merge. phpunit --coverage=coverage
Tests d’intégration (Docker Compose) Valident le flux complet (API ↔ DB). docker-compose up -d + scripts de test
Tests de charge (k6, locust) Détecte les points de rupture sous trafic réel. Scénario “ajouter 100 devis en 30 s”.
Analyse statique (PHPStan, Psalm) Repère les types erronés, les appels inexistants. phpstan analyse src

Bon à savoir : Créez un environnement de pré‑prod qui reproduit exactement la configuration de production (versions PHP, MySQL, extensions Apache/Nginx).

3.2 2. Gestion de la configuration

Pratique Détails
Variables d’environnement (APP_ENV, DB_HOST, CACHE_TYPE) Evite de toucher le code pour changer les paramètres de déploiement.
Fichier .env Chargé par phpdotenv avant l’inclusion du bootstrap.
Séparation des configs config_prod.php vs config_dev.php générés via un template CI.
Ne jamais stocker les mots de passe en clair Utiliser un secret manager (Vault, AWS Secrets Manager).

3.3 3. Sécurisation du serveur web

Mesure Implémentation rapide
HTTPS obligatoire Certificat Let’s Encrypt (certbot).
HSTS (Strict-Transport-Security) add_header Strict-Transport-Security "max-age=31536000; includeSubDomains" always;
Headers de sécurité X-Content-Type-Options, X-Frame-Options, Content-Security-Policy.
Limitation des IPs allow/deny dans Apache ou deny/allow dans Nginx.
Désactivation du listing Options -Indexes.

3.4 4. Gestion des erreurs côté application

  1. Mode développement vs production

    • En prod, désactiver l’affichage des stack traces (display_errors = Off).

    • Rediriger vers un logger centralisé (Monolog).

  2. Journalisation structurée 

    use Monolog\Logger;
    
use Monolog\Handler\SyslogUdpHandler;
    
$log = new Logger('dolibarr');
    
$log->pushHandler(new SyslogUdpHandler('udp://logserver.company.local', 514));
    
$log->error('Erreur de création de facture', ['order_id' => $orderId]);

  3. Gestion des retours API

    • Toujours renvoyer un code HTTP standard (200, 400, 401, 500).

    • Inclure un error.message lisible et un error.code interne.

  4. Circuit Breaker (ex. Hystrix pour PHP)

    • Ajoutez une couche qui interrompt les appels à des services externes si le taux d’échec dépasse un seuil.

3.5 5. Optimisation des requêtes DB

Action Méthode
Indexation Vérifier les EXPLAIN des requêtes fréquentes (ex. SELECT client FROM invoices WHERE date='...';).
Cache d’objets Activer APCu pour les SELECT répétés d’un même client.
Batch writes Regrouper les insertions (INSERT ... VALUES ...) au lieu d’exécuter un INSERT par ligne.
Analyse régulière ANALYZE TABLE hebdomadaire sur les tables lourdes.

3.6 6. Déploiement continu et rollback

Étape Description
CI/CD (GitLab CI, GitHub Actions) Build → Test → Docker image → Push → Déploiement sur serveur staging → Smoke test → Production.
Blue/Green deployment Deux environnements identiques, bascule DNS à chaud.
Rollback automatisé En cas d’erreur (ex. taux d’erreurs > 5 %), le pipeline inverse la dernière version stable.

4. Monitoring et alerting

4.1 Métriques essentielles

Métrique Point de mesure Seuil d’alerte
Temps de réponse moyen du endpoint /api/... curl -s http://.../api/wiki.php/Invoices?range=... > 800 ms → alerte.
Taux d’erreurs HTTP 5xx Prometheus http_requests_total{status=~"5.."} / http_requests_total > 2 % sur 5 min.
Utilisation CPU / RAM du PHP‑FPM process_cpu_seconds_total, process_resident_memory_bytes > 85 % → scaling.
Taille du journal de logs logrotate + du -sh /var/log/dolibarr/ > 2 GB → rotation urgente.
Lag de la file d’attente cron Nombre de jobs en attente > 10 min → notifier.

4.2Centralisation des logs

  • Syslog/Logstash ou Elastic Stack → recherche en temps réel.

  • Graylog pour alertes « occurrence d’événement “exception” ».

  • Taggage : service="dolibarr", env="production".

4.3 Dashboard d’état

Un tableau de bord simple (Grafana) peut afficher :

  • Requests par minute (global et par endpoint).

  • Transactions DB (commits/rollbacks).

  • Version du code (git SHA).

  • État du cache (hits/miss).

5. Gestion des incidents en production

Phase Action recommandée
Détection Alertes automatisées (PagerDuty, Opsgenie).
Qualification Consulter le tableau de bord, identifier la cause racine (logs, métriques).
Isolation Mettre le service concerné en maintenance (ex. désactiver un endpoint).
Réparation Appliquer le correctif rapidement ; si besoin, restaurer la version antérieure via le pipeline de rollback.
Post‑mortem Documenter le scénario, mettre à jour les runbooks, ajouter les assertions manquantes aux tests.
Retrospective Réévaluer les seuils d’alerte et la couverture de tests.

6. Exemple de mise en place d’un endpoint API REST sécurisé

6.1. Structure du code

// src/DolibarrApi.php

namespace App;
use Dolibarr\Component\ApiResponse;

use Dolibarr\DolibarrApp;
class DolibarrApi

{

    private Api $api;

    private Logger $logger;
public function __construct()

    {

        $this->logger = new Logger('dolibarr_api');

        // Auth par token JWT

        $token = $_SERVER['HTTP_AUTHORIZATION'] ?? '';

        $this->api = new DolibarrApp();

        $this->api->initStandalone();

        $this->api->setUserToken($token);

    }
public function getInvoice(string $id): ApiResponse

    {

        if (!$id || !ctype_digit($id)) {

            $this->logger->warning('Invalid/invoice id', ['id' => $id]);

            return ApiResponse::badRequest('ID invalide');

        }
try {

            $sql = "SELECT * FROM invoices WHERE rowid = ?";

            $res = $this->api->db->fetch($sql, true, [$id]);

            if (!$res) {

                return ApiResponse::notFound("Facture $id inexistante");

            }

            return ApiResponse::ok($res);

        } catch (\Exception $e) {

            $this->logger->error('Error fetching invoice', ['id' => $id, 'msg' => $e->getMessage()]);

            return ApiResponse::serverError('Erreur serveur');

        }

    }

}

6.2. Routage (Apache rewrite)

# .htaccess (dans /dolibarr/api)

RewriteEngine On

RewriteRule ^wiki.php/(.*)$ api.php?module=$1 [L,QSA]
RewriteCond %{REQUEST_METHOD} POST [OR]

RewriteCond %{REQUEST_METHOD} PUT [OR]

RewriteCond %{REQUEST_METHOD} DELETE

RewriteRule ^api/ - [R=405,L]

6.3. Retour d’erreur standard

header('Content-Type: application/json');

echo json_encode([

    'error' => $errorMessage,

    'code'  => $errorCode

]);

http_response_code($errorCode);

exit;

7. Checklist “Production‑Ready” (à cocher avant le go‑live)

✅ Item
1 Version de Dolibarr stabilisée (pas de dev ou beta).
2 Configuration config.php générée à partir de variables d’environnement.
3 HTTPS + HSTS + Headers de sécurité configurés.
4 Journalisation centralisée avec niveaux (info, warning, error).
5 Tests automatisés (≥ 80 % de couverture fonctionnelle).
6 Mise à jour des statistiques DB (indexes, ANALYZE).
7 Cache activé (APCu ou Redis) et clearing après déploiement.
8 Rotation des logs (logrotate) fonctionnelle.
9 Secrets stockés hors du dépôt (Vault, env).
10 Backup DB quotidien + test de restauration.
11 Surveillance (Prometheus + Grafana) avec alertes actives.
12 Plan de rollback (tag git et scripts de restauration).
13 Documentation des endpoints API (OpenAPI spec).
14 Routage des erreurs → page error.php générique, pas de stack trace.
15 Performance : temps de réponse < 500 ms pour 95 % des requêtes en pré‑prod.

8. Conclusion

Dolibarr peut très facilement passer d’un petit serveur local à une plateforme industrielle robuste, à condition d’en maîtriser l’architecture web‑service, les processus de déploiement et les pratiques d’observabilité.

En suivant les points clés présentés :

  1. Séparer clairement les environnements (dev → prod) et versionner les configurations.

  2. Automatiser les tests, le build et le déploiement (CI/CD + Blue/Green).

  3. Mettre en place une journalisation structurée et des alertes pour chaque indicateur critique.

  4. Limiter les erreurs grâce à une gestion rigoureuse des exceptions, à la validation d’entrée et à une architecture de cache adaptée.

Vous réduirez drastiquement la probabilité d’incidents en production, tout en conservant la flexibilité qui a fait le succès de Dolibarr.

« La stabilité d’une solution ne réside pas seulement dans son code, mais dans l’ensemble des processus qui l’entourent. » – Good DevOps Culture.

Besoin d’un exemple de pipeline CI/CD complet ou d’un script de backup automatisé ? N’hésitez pas, je suis à votre disposition pour approfondir chaque point.

Publications similaires