Back up and restore Dolibarr

The four things to back up, Dolibarr's built-in automatic backup, and a restore tested on a fresh instance. Without the key in conf.php, customer IBANs and API keys stay unreadable.

Versions concerned
Dolibarr 24.0.1 (tested, official Docker image, MariaDB 11.4); the principle applies to all recent versions
What was checked
Tests on 13/10/2026 on Dolibarr 24.0.1: database backup and documents archive from the interface, scheduled backup job run three times with a retention of 2 files, full restore on a fresh instance (same version), then encrypted data read with the right and with another instance key. Dolibarr code read (dolEncrypt, dolibarr_set_const, Utils::dumpDatabase).

A Dolibarr backup you can really start again from holds four things. The first three are well known; the fourth is almost always forgotten, and without it part of the data stays unreadable after a restore.

We checked everything on 13 October 2026 on Dolibarr 24.0.1: backup, restore on a fresh instance, then reading the data with the right and with a wrong key.

The four things to back up

  1. The database: third parties, invoices, settings, users.
  2. The documents folder: generated PDFs, attached files, logo, ODT templates. Its location is in conf.php, variable $dolibarr_main_data_root.
  3. The custom folder: external modules (from the DoliStore, for instance), in htdocs/custom. The documents archive offered by Dolibarr does not include it.
  4. The instance key, in htdocs/conf/conf.php: $dolibarr_main_instance_unique_id, or $dolibarr_main_dolcrypt_key if it exists. In Docker, it is the DOLI_INSTANCE_UNIQUE_ID variable, so the .env file.

Why the key matters

Dolibarr encrypts some database data with this key:

  • customer IBANs (used for SEPA direct debits);
  • users’ API tokens;
  • settings whose name ends with _KEY, _PASS, _PASSWORD, _PW or _SECRET when entered on screen: email server password, keys of online payment modules…

We restored a database on a fresh instance with another key. The API token was refused (“Error user not valid (not found with api key…)”), and a customer’s IBAN showed as:

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

After putting the right key back, the IBAN was readable again: the data is not lost, but you need the original key. The IBAN of your own bank account is not encrypted.

Backing up from the interface

Admin Tools › Backup offers two wizards:

  • the database: method “MySQL Dump (mysqldump)”, Gzip compression, Generate backup. The file is stored in documents/admin/backup/.
  • the documents folder: the second Generate backup button. The archive is stored in documents/admin/documents/.

Both files stay on the same server: download them from the same page, or they go down with it. The page also mentions the key in conf.php, which it cannot show itself: that takes access to the server’s files.

Backing up automatically, without a script

Dolibarr includes a scheduled backup job, disabled by default. It needs the Scheduled jobs module and a cron that runs it (with Docker, see Install Dolibarr with Docker Compose).

Admin Tools › Scheduled jobs, job Local database backup, Edit. Its parameters, comma-separated:

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

In order: compression (gz, bz or none), database type (auto), 1, file name (auto), number of backups to keep, then two technical options to leave at 0. Set the frequency (once a week by default), save, then enable the job.

Tested with a retention of 2: after three runs, only the last two backups were left. The code comment says this parameter is “not used yet”; it is. As with the manual backup, these files stay on the server: copy them elsewhere.

Backing up from the command line

With Docker and the setup from our install guide, from the project folder:

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

On a regular server the principle is the same: read the database name ($dolibarr_main_db_name), its user and the documents folder in conf.php, then:

mariadb-dump -u user -p database_name | gzip > dolibarr.sql.gz
tar -czf dolibarr-files.tar.gz /path/to/documents /path/to/htdocs/custom /path/to/htdocs/conf/conf.php

With a MySQL server, the command is called mysqldump. On some recent MariaDB installs only mariadb-dump exists: that is the case of the official MariaDB 11.4 image, where mysqldump cannot be found.

A complete database backup ends with -- Dump completed:

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

Restoring, on the same server or a new one

Restore on the same Dolibarr version as the backup: the database structure depends on the version. To change version, restore first, upgrade afterwards. Dolibarr does not allow restoring from the application, for security: everything happens on the server.

With Docker, in this order (the order we tested):

  1. Put the files back: extract data/documents and data/custom, and take the old .env, with the same INSTANCE_UNIQUE_ID.

  2. Start the database alone and wait until it is ready:

    docker compose up -d db

  3. Import the backup:

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

  4. Start Dolibarr:

    docker compose up -d

    The log (docker compose logs web) must say “install.lock exists and database exists so we cancel database init”: the image recognised an existing install and does not create a new one.

  5. Log in with an administrator account that existed when the backup was made.

In our test everything was there: the 13 invoices and their PDFs, the custom folder, the administrator login and the API token, accepted because the instance key was the same.

On a regular server: install the same Dolibarr version, put back the documents and custom folders, copy the instance key into the new conf.php, import the database with mariadb (or mysql with a MySQL server), then log in.

If you no longer have the key

Encrypted data is not lost, but unreadable. If you find the old conf.php, just put the key back: everything becomes readable again. Otherwise, enter the customer IBANs again, regenerate the API tokens, and re-enter the email server password and the payment module keys.

Test your backup

A backup that has never been restored is only an assumption. Restore it now and then on a separate instance, as in this test, and check that an invoice opens and its PDF displays.

It is also the first step of any upgrade: the Safe upgrade package starts with this copy and keeps a rollback backup ready.

See also

Dolibarrbackuprestoremigrationservermysqldumpconf.php