How to Migrate Dolibarr to a New Server Without Losing Data: A Complete Guide

Table of Contents

1. Introduction

2. Why You Might Need to Migrate Dolibarr

3. Understanding Dolibarr’s File and Database Structure

4. Preparing for a Migration: Backup Strategy

5. Choosing Your New Hosting Environment

6. Installing Prerequisites on the New Server

7. Backing Up the Dolibarr Database

8. Exporting Dolibarr’s Document and Configuration Files

9. Transferring Files Securely to the New Server

10. Restoring the Database on the New Server

11. Adjusting the Configuration File (conf.php)

12. Setting Permissions and Directory Ownerships

13. Testing the Restored Instance

14. DNS and Domain Propagation Considerations

15. Dealing with Version Differences During Migration

16. Cleaning Up and Optimizing Post-Migration

17. Common Errors and How to Fix Them

18. Migrating Custom Modules and Plugins

19. Ensuring Compatibility with External Integrations

20. Data Integrity Checks After Migration

21. Handling User Access During the Switch

22. Final Backup and Rollback Plan

23. Security Best Practices During Migration

24. Scheduling Downtime and Communicating with Stakeholders

25. Conclusion: Reliable Migration Without Data Loss

1. Introduction

Migrating your Dolibarr ERP/CRM system to a new server may sound daunting, especially when data integrity and service continuity are critical. Whether you're switching hosting providers, upgrading hardware, or moving to a private cloud, this guide walks you step-by-step through the migration process—without losing a single byte of data.

2. Why You Might Need to Migrate Dolibarr

Common scenarios include:

• Changing from shared hosting to VPS or dedicated hosting

• Moving from a test server to production

• Switching to a cloud provider

• Upgrading the OS or infrastructure

Migration ensures better performance, flexibility, or security—when done correctly.

3. Understanding Dolibarr’s File and Database Structure

Dolibarr relies on two main components:

• Database (MySQL/MariaDB): Stores all business data—clients, invoices, inventory, etc.

• File system: Contains configuration files, modules, user-uploaded documents (PDFs, images), and the /htdocs/ application folder

You need both for a complete migration.

4. Preparing for a Migration: Backup Strategy

Before doing anything:

• Backup the database using mysqldump

• Archive the full Dolibarr directory (e.g., /var/www/dolibarr)

• Store backups in two secure locations

It’s also wise to notify users about the maintenance window and temporarily disable write access.

5. Choosing Your New Hosting Environment

Make sure your new server supports:

• PHP 7.4+ or PHP 8.1+

• MySQL or MariaDB

• Apache or Nginx

• Required PHP extensions: gd, curl, mbstring, json, etc.

Avoid incompatible or older server stacks.

6. Installing Prerequisites on the New Server

Install necessary packages:

sudo apt update
sudo apt install apache2 mariadb-server php php-mysql php-gd php-curl php-mbstring php-xml unzip

Then enable the required Apache modules:

sudo a2enmod rewrite ssl
sudo systemctl restart apache2

7. Backing Up the Dolibarr Database

Use mysqldump or phpMyAdmin:

mysqldump -u root -p dolibarr_db > dolibarr_backup.sql

Ensure your dump includes:

• All tables

• Table structure and data

• UTF-8 charset (for non-English characters)

8. Exporting Dolibarr’s Document and Configuration Files

Use tar or zip to archive your Dolibarr folder:

tar czf dolibarr_files.tar.gz /var/www/dolibarr

This preserves directory structure, permissions, and symbolic links.

9. Transferring Files Securely to the New Server

Use scp or rsync for secure transfer:

scp dolibarr_backup.sql user@newserver:/home/user/
scp dolibarr_files.tar.gz user@newserver:/home/user/

Alternatively, use SFTP or a USB device in air-gapped environments.

10. Restoring the Database on the New Server

Log into MySQL and import:

mysql -u root -p
CREATE DATABASE dolibarr_db CHARACTER SET utf8mb4 COLLATE utf8mb4_general_ci;
exit
mysql -u root -p dolibarr_db < dolibarr_backup.sql

Make sure the user credentials match those in conf.php.

11. Adjusting the Configuration File (conf.php)

Open htdocs/conf/conf.php and update:

• db_host

• db_user

• db_pass

• db_name

• dolibarr_main_url_root

Make sure URLs match the new server domain or IP.

12. Setting Permissions and Directory Ownerships

Set the right user permissions:

chown -R www-data:www-data /var/www/dolibarr
chmod -R 755 /var/www/dolibarr

These ensure web server access to Dolibarr files.

13. Testing the Restored Instance

Browse to your Dolibarr login page at the new URL. Verify:

• Database connectivity

• Login functionality

• PDF generation

• Module activation

Use browser dev tools or PHP error logs to debug issues.

14. DNS and Domain Propagation Considerations

If you’re switching domains:

• Update DNS A records to the new server IP

• Configure HTTPS with Let’s Encrypt or other SSL

• Allow 24–48 hours for global DNS propagation

15. Dealing with Version Differences During Migration

If your new server uses a newer Dolibarr version:

• Follow upgrade procedures before migration

• Run the Dolibarr installer at /install/ to update the database schema

Never restore an older backup to a newer installation without migration steps.

16. Cleaning Up and Optimizing Post-Migration

Post-migration tasks include:

• Deleting .sql and .tar.gz backup files

• Removing temporary or cache folders

• Running database optimization scripts

• Checking for unused modules or data

17. Common Errors and How to Fix Them

18. Migrating Custom Modules and Plugins

Copy all custom modules from: /htdocs/custom/

Also migrate:

• Language files

• Custom themes or CSS

• Templates and additional hooks

Be sure they’re compatible with your Dolibarr version.

19. Ensuring Compatibility with External Integrations

After migration, test:

• API endpoints

• WooCommerce or Prestashop bridges

• Email SMTP settings

• Webhooks or CRON scripts

Update IPs or tokens as needed in connected platforms.

20. Data Integrity Checks After Migration

Validate:

• Invoice totals match old records

• Customer and supplier data is intact

• Reports match pre-migration snapshots

• No missing files in /documents/

Use SQL queries to double-check random records.

21. Handling User Access During the Switch

Best practice:

• Inform users in advance

• Freeze access during backup

• Allow access only after testing on new server

Consider setting a temporary read-only mode if downtime is minimal.

22. Final Backup and Rollback Plan

Always:

• Backup new server after successful migration

• Retain old server snapshot for at least 7 days

• Document all steps and issues during migration

This provides a safety net in case of post-migration bugs.

23. Security Best Practices During Migration

• Use SSH/SFTP, not FTP

• Rotate DB and admin passwords post-migration

• Secure your new server’s firewall and PHP settings

• Enable HTTPS immediately

24. Scheduling Downtime and Communicating with Stakeholders

Notify clients and users:

• Expected downtime window

• Any changes to URLs or logins

• Support contacts in case of issues

Schedule migration during off-peak hours if possible.

25. Conclusion: Reliable Migration Without Data Loss

Migrating Dolibarr to a new server is safe and manageable with the right steps. By planning carefully, backing up thoroughly, and verifying each stage, you can transition to a more powerful infrastructure or hosting provider without service disruption or data loss.

Whether you’re scaling your operations or improving security, this migration will help ensure that Dolibarr remains a stable backbone of your business operations.