Sauvegarder et restaurer Dolibarr

Les quatre éléments à sauvegarder, la sauvegarde automatique intégrée à Dolibarr, et une restauration testée sur une instance neuve. Sans la clé de conf.php, les IBAN clients et les clés API restent illisibles.

Versions concernées
Dolibarr 24.0.1 (testé, image Docker officielle, MariaDB 11.4) ; le principe vaut pour toutes les versions récentes
Ce qui a été vérifié
Tests du 13/10/2026 sur Dolibarr 24.0.1 : sauvegarde de la base et archive des documents depuis l'interface, tâche planifiée de sauvegarde lancée trois fois avec une rétention de 2 fichiers, restauration complète sur une instance neuve (même version), puis lecture des données chiffrées avec la bonne et avec une autre clé d'instance. Lecture du code de Dolibarr (dolEncrypt, dolibarr_set_const, Utils::dumpDatabase).

Une sauvegarde de Dolibarr qui permet vraiment de repartir contient quatre éléments. Les trois premiers sont connus ; le quatrième est presque toujours oublié, et sans lui une partie des données reste illisible après la restauration.

Nous avons tout vérifié le 13 octobre 2026 sur Dolibarr 24.0.1 : sauvegarde, restauration sur une instance neuve, puis lecture des données avec la bonne et avec une mauvaise clé.

Les quatre éléments à sauvegarder

  1. La base de données : tiers, factures, réglages, utilisateurs.
  2. Le dossier documents : PDF générés, fichiers joints, logo, modèles ODT. Son emplacement est dans conf.php, variable $dolibarr_main_data_root.
  3. Le dossier custom : les modules externes (ceux du DoliStore, par exemple), dans htdocs/custom. L’archive des documents proposée par Dolibarr ne le contient pas.
  4. La clé d’instance, dans htdocs/conf/conf.php : $dolibarr_main_instance_unique_id, ou $dolibarr_main_dolcrypt_key si elle existe. Sous Docker, c’est la variable DOLI_INSTANCE_UNIQUE_ID, donc le fichier .env.

Pourquoi la clé compte

Dolibarr chiffre avec cette clé certaines données de la base :

  • les IBAN des clients (utilisés pour les prélèvements SEPA) ;
  • les jetons API des utilisateurs ;
  • les réglages dont le nom se termine par _KEY, _PASS, _PASSWORD, _PW ou _SECRET quand ils sont saisis depuis l’écran : mot de passe du serveur d’e-mails, clés des modules de paiement en ligne…

Nous avons restauré une base sur une instance neuve avec une autre clé. Le jeton API a été refusé (« Error user not valid (not found with api key…) »), et l’IBAN d’un client s’affichait ainsi :

dolcrypt:AES-256-CTR:5efe1028549de1db:HSkQmbe/oNN7CN/CER+o5uHUC5qQN70IWV2T

En remettant la bonne clé, l’IBAN est redevenu lisible : les données ne sont pas perdues, mais il faut la clé d’origine. L’IBAN de votre compte bancaire, lui, n’est pas chiffré.

Sauvegarder depuis l’interface

Outils d’administration › Sauvegarde propose deux assistants :

  • la base : méthode « MySQL Dump (mysqldump) », compression Gzip, Générer sauvegarde. Le fichier est rangé dans documents/admin/backup/.
  • le dossier documents : second bouton Générer sauvegarde. L’archive est rangée dans documents/admin/documents/.

Les deux fichiers restent sur le même serveur : téléchargez-les depuis la même page, sinon ils disparaissent avec lui. La page rappelle aussi la clé de conf.php, qu’elle ne peut pas afficher elle-même : il faut un accès aux fichiers du serveur.

Sauvegarder automatiquement, sans script

Dolibarr contient une tâche planifiée de sauvegarde, désactivée par défaut. Il faut le module Travaux planifiés et un cron qui l’exécute (avec Docker, voir Installer Dolibarr avec Docker Compose).

Outils d’administration › Travaux planifiés, tâche Sauvegarde locale de base, Éditer. Ses paramètres, séparés par des virgules :

gz,auto,1,auto,10,0,0

Dans l’ordre : compression (gz, bz ou none), type de base (auto), 1, nom du fichier (auto), nombre de sauvegardes à garder, puis deux options techniques à laisser à 0. Réglez la fréquence (par défaut une fois par semaine), enregistrez, puis activez la tâche.

Testé avec une rétention de 2 : après trois exécutions, seules les deux dernières sauvegardes restaient. Le commentaire du code dit que ce paramètre n’est « pas encore utilisé » ; il l’est. Comme pour la sauvegarde manuelle, ces fichiers restent sur le serveur : copiez-les ailleurs.

Sauvegarder en ligne de commande

Avec Docker et la configuration de notre guide d’installation, depuis le dossier du projet :

docker compose exec -T db sh -c 'mariadb-dump -u"$MARIADB_USER" -p"$MARIADB_PASSWORD" "$MARIADB_DATABASE"' | gzip > dolibarr.sql.gz
tar -czf dolibarr-fichiers.tar.gz data/documents data/custom .env docker-compose.yml

Sur un serveur classique, le principe est le même : lisez dans conf.php le nom de la base ($dolibarr_main_db_name), son utilisateur et le dossier des documents, puis :

mariadb-dump -u utilisateur -p nom_de_la_base | gzip > dolibarr.sql.gz
tar -czf dolibarr-fichiers.tar.gz /chemin/vers/documents /chemin/vers/htdocs/custom /chemin/vers/htdocs/conf/conf.php

Avec un serveur MySQL, la commande s’appelle mysqldump. Sur certaines installations récentes de MariaDB, seule mariadb-dump existe : c’est le cas de l’image officielle de MariaDB 11.4, où mysqldump est introuvable.

Une sauvegarde de base complète se termine par -- Dump completed :

gzip -dc dolibarr.sql.gz | tail -1

Restaurer, sur le même serveur ou sur un nouveau

Restaurez sur la même version de Dolibarr que celle de la sauvegarde : la structure de la base dépend de la version. Pour changer de version, restaurez d’abord, mettez à jour ensuite. Dolibarr ne permet pas de restaurer depuis l’application, par sécurité : tout se fait sur le serveur.

Avec Docker, dans cet ordre (c’est l’ordre que nous avons testé) :

  1. Remettez les fichiers : extrayez data/documents et data/custom, et reprenez l’ancien .env, avec la même INSTANCE_UNIQUE_ID.

  2. Démarrez la base seule et attendez qu’elle soit prête :

    docker compose up -d db

  3. Importez la sauvegarde :

    gzip -dc dolibarr.sql.gz | docker compose exec -T db sh -c 'mariadb -u"$MARIADB_USER" -p"$MARIADB_PASSWORD" "$MARIADB_DATABASE"'

  4. Démarrez Dolibarr :

    docker compose up -d

    Le journal (docker compose logs web) doit indiquer « install.lock exists and database exists so we cancel database init » : l’image a reconnu une installation existante et n’en crée pas une nouvelle.

  5. Connectez-vous avec un compte administrateur qui existait au moment de la sauvegarde.

Sur notre test, tout était là : les 13 factures et leurs PDF, le dossier custom, la connexion de l’administrateur et le jeton API, accepté puisque la clé d’instance était la même.

Sur un serveur classique : installez la même version de Dolibarr, remettez les dossiers documents et custom, reprenez la clé d’instance dans le nouveau conf.php, importez la base avec mariadb (ou mysql avec un serveur MySQL), puis connectez-vous.

Si vous n’avez plus la clé

Les données chiffrées ne sont pas perdues, mais illisibles. Si vous retrouvez l’ancien conf.php, remettez simplement la clé : tout redevient lisible. Sinon, saisissez à nouveau les IBAN des clients, regénérez les jetons API, et ressaisissez le mot de passe du serveur d’e-mails et les clés des modules de paiement.

Testez votre sauvegarde

Une sauvegarde qui n’a jamais été restaurée n’est qu’une supposition. Restaurez-la de temps en temps sur une instance séparée, comme dans ce test, et vérifiez qu’une facture s’ouvre et que son PDF s’affiche.

C’est aussi la première étape de toute mise à jour : le forfait Mise à jour sécurisée commence par cette copie, et garde une sauvegarde de retour prête.

À lire aussi

Dolibarrsauvegarderestaurationbackupmigrationserveurmysqldumpconf.php