API Dolibarr : Letʼs Encrypt Stratégie pour passer à l’échelle

Guide pratique en français pour sécuriser et dimensionner votre plateforme Dolibarr avec des certificats Let’s Encrypt automatisés.

1. Introduction

Dolibarr est un ERP/CRM open‑source très répandu, mais lorsqu’il est déployé en production sur plusieurs serveurs, la gestion des certificats TLS/SSL devient un vrai défi.
Let’s Encrypt offre une solution gratuite, automatisée et reconnue, parfaitement adaptée aux environnements conteneurs, VM ou serveurs bare‑metal.

Cet article détaille :

  1. Pourquoi choisir Let’s Encrypt avec Dolibarr.

  2. Comment l’intégrer via l’API Dolibarr (et via le serveur web).

  3. La mise en place d’une stratégie de scaling (horizontal & vertical) tout en maintenant la sécurité TLS.

  4. Les bonnes pratiques, erreurs courantes et outils d’automatisation.

2. Pourquoi Let’s Encrypt ?

Avantage Impact sur votre architecture Dolibarr
Gratuité Réduction de coût d’infrastructure, aucune licence SSL à renouveler.
Renouvellement automatique Les certificats expirent au bout de 90 jours ; il suffit de relancer le challenge pour les renouveler.
Autorité de confiance reconnue Aucun navigateur ne signale le certificat comme « non fiable », ce qui rassure les utilisateurs internes et externes.
Écosystème CI/CD De nombreux scripts, API et clients (certbot, acme.sh, lego) s’intègrent naturellement avec les pipelines de déploiement.
Sécurité TLS dès le départ Les certificats sont émis avec des configurations modernes (TLS 1.3, HSTS, OCSP stapling).

En bref : Let’s Encrypt vous évite de gérer manuellement les CSR, les renewals et les renouvellements de CA, ce qui est crucial lorsqu’on scale à plusieurs instances derrière un load‑balancer.

3. Architecture recommandée

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

│   Load‑Balancer (LB)│◄─────►─────►│   Serveur Web N     │   (Dolibarr + PHP‑FPM) 

│   (nginx/HAProxy)   │           │   (Docker/VM)       │

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

          ▲                               ▲

          │                               │

          │   Let's Encrypt ACME Client    │   Certificat TLS partagé

          │   (certbot / acme.sh / lego)   │   (renouvelé automatiquement)

          ▼                               ▼

   Challenge HTTP‑01 / DNS‑01     →   TLS termination

3.1. Points clés à prendre en compte

  1. Un seul point d’entrée TLS : Toutes les instances de Dolibarr derrière le LB partagent le même certificat Let’s Encrypt (via SNI ou IP partagée).

  2. Challenge HTTP‑01 : Le serveur public expose /.well-known/acme-challenge/ accessible via le LB.

  3. Délivrance du certificat : Le client ACME doit tourner sur chaque instance ou sur un agent centralisé (ex : un serveur dédié qui gère le défi pour toutes les instances).

  4. Renouvellement synchronisé : Un job cron partagé doit appeler le même script sur chaque nœud ou utiliser le hook post‑renewal pour rechargernginx/HAProxy.

4. Intégrer l’API Dolibarr avec Let’s Encrypt

4.1. API native de Dolibarr (REST / JSON)

Dolibarr expose une API REST (actuellement en v12 et v13). Vous pouvez :

  • Activer le service dans Administration → Configuration → Server parameters → “Enable API”.

  • Générer une clef API (token) pour les appels externes.

  • Utiliser des bibliothèques PHP (ex : php-dolibarr-client) ou curl pour interroger https://api.monserveur.com/dolibarr/api.php.

Exemple d’appel sécurisé (PHP)

<?php

$apiUrl = 'https://dolibarr.example.com/api.php';

$token  = 'YOUR_API_TOKEN';
$data = [

    'action'    => 'getCustomer',

    'usertoken' => $token,

    'format'    => 'json',

    'id'        => 12

];
$ch = curl_init($apiUrl);

curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);

curl_setopt($ch, CURLOPT_POSTFIELDS, http_build_query($data));

curl_setopt($ch, CURLOPT_HTTPHEADER, [

    'Content-Type: application/x-www-form-urlencoded'

]);
$response = curl_exec($ch);

curl_close($ch);
echo $response;

?>

Note sécurité : Le trafic vers l’API doit toujours passer par HTTPS avec un certificat Let’s Encrypt valide ; sinon, les tokens sont vulnérables au MITM.

4.2. Gestion du renouvellement côté API

Lorsque vous utilisez le client ACME (ex : certbot sur un conteneur), pensez à :

  • Configurer le répertoire challenge accessible par l’API (par ex. /var/www/acme-challenge/).

  • Injecter la variable d’environnement LE_WORKING_DIR afin que le client renvoie le certificat dans le répertoire /etc/letsencrypt/live/<domain>/.

  • Recharger le serveur web à chaque renouvellement :

#!/bin/bash

certbot renew --post-hook "service nginx reload"

Cette commande peut être orchestrée via Kubernetes CronJob ou systemd timers.

5. Stratégie de scaling avec Let’s Encrypt

5.1. Scaling horizontal (multiples containers ou VM)

Étape Action Outil / Technique
1️⃣ Provisionner un Ingress (NGINX, Traefik, Istio) qui expose le service à l’extérieur. Traefik auto‑gère le TLS‑Let’s Encrypt via le ACME‑Challenge intégré.
2️⃣ Déployer cert‑bot ou lego comme side‑car dans chaque pod. Kubernetes init‑container qui crée le challenge avant le démarrage du service.
3️⃣ Utiliser le sharing of certificates (PV ou ConfigMap) pour éviter la duplication. ConfigMap monté en lecture‑seule contenant le certificat délivré.
4️⃣ Automatiser le renouvellement via CronJob ou cert-manager. cert-manager + ClusterIssuer Let’s Encrypt.
5️⃣ S’assurer que le LB (ou Ingress) dirige le trafic HTTP‑01 vers tous les pods. Avec Ingress basé sur path‑based routing, chaque pod possède son propre /.well-known/acme-challenge/.

Exemple de ClusterIssuer Let’s Encrypt (YAML) :

apiVersion: cert-manager.io/v1

kind: ClusterIssuer

metadata:

  name: letsencrypt-prod

spec:

  acme:

    server: https://acme-v02.api.letsencrypt.org/directory

    email: admin@example.com

    privateKeySecretRef:

      name: letsencrypt-prod-key

    solvers:

    - http01:

        ingress:

          class: nginx

Ensuite, associez votre Ingress à ce ClusterIssuer :

apiVersion: networking.k8s.io/v1

kind: Ingress

metadata:

  name: dolibarr-ingress

  annotations:

    cert-manager.io/cluster-issuer: letsencrypt-prod

spec:

  rules:

  - host: dolibarr.example.com

    http:

      paths:

      - path: /

        pathType: Prefix

        backend:

          service:

            name: dolibarr-svc

            port:

              number: 80

  tls:

  - hosts:

    - dolibarr.example.com

    secretName: dolibarr-tls

5.2. Scaling vertical (plus de ressources)

  • CPU/Memory : Augmentez les limites de conteneurs (ex : 2 vCPU + 4 GiB) pour supporter plus de requêtes concurrentes.

  • Cache & Session : Activez APACHE ou NGINX sticky sessions et configurez un Redis partagé pour les sessions PHP afin d’éviter les “session lost” lors d’un scale‑out.

  • Database : Externalisez MySQL/MariaDB vers un cluster (Galera, Percona XTRO) ; configurez le pool de connexion avec max_pool_time.

Astuce : Lorsque vous passez à plus de ressources, ne modifiez pas le domain (ou le SNI) afin de ne pas perdre le certificat déjà délivré. Le serveur web doit simplement recharger le même certificat (pas besoin de re‑émission).

6. Bonnes pratiques & pièges à éviter

Bonne pratique Pourquoi Comment la mettre en place
Toujours forcer le protocole TLS 1.2+ Protocoles obsolètes sont une faille de sécurité. Ajoutez ssl_protocols TLSv1.2 TLSv1.3; dans votre configuration NGINX/Apache.
Activer HSTS Informe les navigateurs de forcer HTTPS pendant 1 an. add_header Strict-Transport-Security "max-age=31536000; includeSubDomains" always;
Utiliser le challenge DNS‑01 en mode headless (si vous avez un DNS interne) Permet le renouvellement sans exposition publique du challenge. Créez un cert-manager DNS‑01 Provider (ex : Route53, Cloudflare) dans votre cluster.
Limiter les IP du challenge Empêche les abus du endpoint ACME. Restreignez l’accès /acme-challenge/ à votre réseau ou à votre LB uniquement.
Surveiller les renouvellements Les logs peuvent cacher des échecs silencieux. Exportez les sorties de certbot renew --dry-run vers Prometheus ou Grafana.
Sauvegarder la clé privée En cas de perte du serveur, vous devez ré‑émettre rapidement. ls -l /etc/letsencrypt/live/ → sauvegarde locale ou S3.

Pièges fréquents

  1. Challenge bloqué par le firewall – Ouvrez le port 80 (HTTP) et le port 443 (HTTPS) sur le LB.

  2. Mauvaise propagation DNS – Vérifiez le TTL et utilisez dig +trace <domain> avant le renouvellement.

  3. Cache CDN avant le renouvellement – Si vous passez par un CDN, videz le cache ou désactivez la mise en cache du défi.

  4. Mauvaises permissions sur le répertoire /.well-known/acme-challenge/ – Le service web doit être capable d’écrire dans ce répertoire (généralement chmod 755 ou 644 pour les fichiers créés par le client).

7. Exemple de pipeline CI/CD avec Let’s Encrypt

# .github/workflows/deploy.yml

name: Deploy Dolibarr (Let’s Encrypt)
on:

  push:

    branches: [ main ]
jobs:

  build-and-deploy:

    runs-on: ubuntu-latest

    steps:

      - name: Checkout repo

        uses: actions/checkout@v3
- name: Build Docker image

        run: |

          docker build -t myorg/dolibarr:${{ github.sha }} .
- name: Push image to registry

        uses: docker/setup-qemu-action@v2

        with:

          platforms: all

      - name: Login to Docker Hub

        uses: docker/login-action@v2

        with:

          username: ${{ secrets.DOCKER_USER }}

          password: ${{ secrets.DOCKER_PASS }}
- name: Deploy to Kubernetes

        uses: azure/k8s-deploy@v4

        with:

          manifests: |

            k8s/deployment.yaml

            k8s/service.yaml

            k8s/ingress.yaml
- name: Trigger cert-manager renewal

        run: |

          kubectl annotate certificate -n cert-manager cert-manager.io/force-renewal=true

  • Effet : Chaque déploiement déclenche le contrôleur cert-manager qui force le renouvellement du certificat (si besoin) et rechargement du Ingress.

  • Résultat : Aucun temps d’arrêt, tous les pods utilisent les mêmes certificats valides.

8. Conclusion

Passer à l’échelle avec Dolibarr tout en conservant une sécurité TLS repose sur trois piliers :

  1. Let’s Encrypt : certificats gratuits, automatisés et reconnus.

  2. API Dolibarr : sécuriser les échanges via HTTPS et utiliser les tokens d’API pour les intégrations externes.

  3. Scaling orchestré : Ingress/TLS‑termination partagée, défi ACME centralisé, renouvellement automatisé avec cert-manager ou cron Kubernetes.

En suivant la feuille de route ci‑dessus, vous pourrez :

  • Déployer des dizaines de pods Dolibarr sans perdre le contrôle du certificat.

  • Garantir une disponibilité 99,9 % grâce à des reloads transparents.

  • Réduire les coûts d’infrastructure tout en respectant les meilleures pratiques de sécurité.

À retenir : Le secret d’une mise à l’échelle réussie réside dans l’automatisation du cycle de vie du certificat et la centralisation du point d’entrée TLS. Un petit script de renewal intégré à votre pipeline CI/CD suffit souvent à transformer un déploiement « manual » en une plateforme prête pour le cloud‑native.

Bonne mise à l’échelle, et n’hésitez pas à tester les mêmes principes avec d’autres services (mail, authentification LDAP, etc.) pour une infrastructure complètement HTTPS‑first !

Vous avez une question précise sur votre configuration actuelle ? Laissez un commentaire ou contactez‑nous via le forum Dolibarr.

Publications similaires