Upgrading Dolibarr ERP/CRM is a crucial process for maintaining the security, performance, and feature set of your business management system. With version 19.0.1 introducing significant improvements and fixes over 17.0.0, many users are understandably eager to upgrade. However, such an upgrade requires careful preparation and execution to avoid data loss, service disruption, or compatibility issues.

This detailed guide walks you through every step necessary to upgrade Dolibarr from version 17.0.0 to 19.0.1 safely and efficiently. Whether you’re a system administrator managing a production instance or a tech-savvy business owner handling your own installation, this article will help you upgrade with confidence.

Understanding the Changes Between 17.0.0 and 19.0.1

Before proceeding with the upgrade, it’s important to understand what’s new between these two versions. Dolibarr 18.x and 19.x introduced changes in modules, the core structure, security, and UI/UX.

Highlights include:

• Improved REST API capabilities

• Enhanced POS module

• Revamped email templates and document generation

• Better PHP 8.x support

• New permissions and security fixes

• Updates to third-party libraries

Refer to the official Dolibarr changelogs for detailed notes on each version. Make sure none of your essential features or modules will break due to deprecated functionalities.

Step 1: Review System Requirements for Dolibarr 19.0.1

Dolibarr 19.0.1 requires specific versions of PHP, MySQL/MariaDB, and Apache/Nginx to operate efficiently. Upgrading without verifying compatibility may result in a broken instance.

Minimum requirements:

• PHP: 7.4 to 8.2 (recommended 8.1+)

• MySQL: 5.7+ or MariaDB 10.3+

• Apache 2.4+ or Nginx with PHP-FPM

• Disk space: At least 1 GB free for upgrade operations

Use the command line or phpinfo() to check your current stack. If your environment does not meet the requirements, upgrade your server stack first.

Step 2: Prepare a Full Backup (Files + Database)

Before any upgrade, it is absolutely essential to back up both your database and Dolibarr files. This allows you to restore the system in case anything goes wrong.

To back up:

• Files: Use rsync, scp, or compress the entire Dolibarr directory:

  tar -czvf dolibarr_backup_1700.tar.gz /var/www/html/dolibarr

• Database: Use mysqldump or a GUI like phpMyAdmin:

  mysqldump -u root -p dolibarr_db > dolibarr_db_1700.sql

Store these backups in a separate location or cloud storage. Consider versioning and labeling with timestamps.

Step 3: Test the Upgrade on a Staging Server

Avoid upgrading your live Dolibarr installation without testing. Clone your production environment onto a staging server to perform a dry-run upgrade.

Steps:

• Deploy a LAMP/LEMP stack identical to production

• Copy files and restore the database

• Point a subdomain or localhost setup to test the site

• Perform the upgrade (see below)

This will help identify any compatibility issues with custom modules, themes, or third-party integrations.

Step 4: Download the Dolibarr 19.0.1 Package

Always download the official stable release from the Dolibarr GitHub releases or dolibarr.org.

Direct link: https://github.com/Dolibarr/dolibarr/releases

Choose the .tgz or .zip package depending on your environment. Avoid nightly builds or development branches unless you are contributing or testing bleeding-edge features.

Step 5: Put Your Site in Maintenance Mode (Optional)

If upgrading on a live server:

• Notify users in advance

• Restrict web access using .htaccess or firewall rules

• You can display a “maintenance.html” file or block all connections except your IP

This prevents data changes during the upgrade process.

Step 6: Replace Files with the New Version

Remove the current Dolibarr files but retain your configuration and custom documents:

Steps:

1. Extract the new archive:

   tar -xvzf dolibarr-19.0.1.tgz

2. Remove all files in your Dolibarr web root except:

   • htdocs/conf/conf.php

   • /documents/ folder

   • Any custom modules or scripts in /custom/

3. Copy the new files over:

   cp -r dolibarr-19.0.1/htdocs/* /var/www/html/dolibarr/

4. Set correct permissions:

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

Step 7: Run the Upgrade Wizard

Navigate to:

http://yourdomain.com/install/

Dolibarr will detect the version difference and start the upgrade wizard.

Follow the on-screen instructions:

• Confirm database migration

• Wait for each step to complete

• Do not interrupt the process

At the end, Dolibarr will notify you of a successful upgrade and remove the /install/ directory for security.

Step 8: Verify Functionality Post-Upgrade

After a successful upgrade:

• Log in with admin credentials

• Check that your data (customers, invoices, products) is intact

• Test custom modules or plugins

• Open logs (admin/system/about.php) for any warnings

• Check document generation, PDF templates, and emails

• Run a few sample operations (invoice creation, product update)

If you use external integrations (e.g., payment gateways, WooCommerce, or APIs), validate that they still function.

Step 9: Enable Maintenance Logs and Security

Post-upgrade best practices include:

• Enable audit logs

• Rotate and secure logs

• Review user permissions

• Regenerate SSL certificates if expired

• Update firewall rules or security plugins if used

Step 10: Inform Users and Resume Normal Operations

Once everything is tested:

• Re-enable access for all users

• Send out communication detailing new features or UI changes

• Provide training or documentation links for users unfamiliar with the new version

Handling Upgrade Errors or Rollbacks

Common issues:

• Blank page or HTTP 500: Check PHP error logs

• Database errors: Possibly incomplete upgrade — restore backup

• Missing modules: May need to reinstall or update

To rollback:

• Stop the web server

• Restore the previous Dolibarr directory

• Import the SQL backup

• Restart services

Conclusion: Upgrade with Confidence

Upgrading from Dolibarr 17.0.0 to 19.0.1 can be smooth and risk-free if done methodically. This guide covered everything from preparation and backups to testing and deployment. By following these steps, you ensure your business remains secure, your features up-to-date, and your system optimized.

Remember: Never upgrade without backups, and always test on a staging environment first. With careful execution, the benefits of version 19.0.1 far outweigh the risks.