Table of Contents
-
Introduction
-
Overview of Dolibarr Installation Requirements
-
Issue 1: Blank Page After Launching Installer
-
Issue 2: PHP Version Incompatibility
-
Issue 3: Missing PHP Extensions
-
Issue 4: File Permission Problems
-
Issue 5: Database Connection Errors
-
Issue 6: Incomplete Installation Wizard
-
Issue 7: install.lock Not Created
-
Issue 8: Conf.php File Not Writable
-
Issue 9: Apache or Nginx Configuration Errors
-
Issue 10: URL Rewrite and .htaccess Issues
-
Issue 11: Timeouts During Installation
-
Issue 12: Language Pack Installation Failures
-
Issue 13: HTTPS or SSL Errors
-
Issue 14: Problems with Shared Hosting Environments
-
Issue 15: Reinstallation Loop
-
Tools to Help Troubleshoot Installation Problems
-
Best Practices to Prevent Installation Errors
-
Conclusion
1. Introduction
Dolibarr is a robust and flexible ERP/CRM solution, but like any web-based application, its installation process can sometimes be hindered by server configuration, missing dependencies, or missteps during setup. This article presents a detailed analysis of the most common installation issues users face and provides actionable solutions.
2. Overview of Dolibarr Installation Requirements
Before beginning, ensure the server meets these requirements:
-
PHP 7.4 to 8.2
-
MySQL 5.7+ or MariaDB 10+
-
Apache/Nginx with mod_rewrite enabled
-
Required PHP extensions: pdo_mysql, gd, intl, zip, curl, json, mbstring, fileinfo
-
Writable directories:
htdocs/conf/
,documents/
, andinstall/
Installing Dolibarr involves uploading the package, running the /install/
script, configuring the database, and finalizing setup.
3. Issue 1: Blank Page After Launching Installer
Symptoms:
-
Navigating to
/install/
yields a white or blank screen.
Causes:
-
PHP error or fatal exception.
Solutions:
-
Enable error reporting in
php.ini
:display_errors = On
-
Check web server logs (
/var/log/apache2/error.log
or/var/log/nginx/error.log
) -
Ensure required PHP modules are installed
-
Use a different PHP version if the current one is buggy
4. Issue 2: PHP Version Incompatibility
Symptoms:
-
Deprecated warnings or function errors.
Causes:
-
Using an unsupported PHP version.
Solutions:
-
Use PHP 7.4 to 8.2, as per Dolibarr’s compatibility chart
-
Install proper version using your server’s package manager or tools like
phpbrew
orupdate-alternatives
-
Restart the web server after switching PHP version
5. Issue 3: Missing PHP Extensions
Symptoms:
-
Installer reports missing modules (e.g., intl, curl).
Causes:
-
Required PHP extensions not installed or not enabled.
Solutions:
-
Install extensions via package manager:
sudo apt install php-intl php-curl php-gd php-mbstring
-
Check
phpinfo()
for confirmation -
Restart Apache or Nginx after changes
6. Issue 4: File Permission Problems
Symptoms:
-
Configuration file not saved
-
Uploads not working
Causes:
-
Incorrect write permissions on required folders
Solutions:
-
Set ownership:
chown -R www-data:www-data /var/www/html/dolibarr
-
Set permissions:
chmod -R 755 /var/www/html/dolibarr
-
Ensure SELinux or AppArmor is not blocking write access
7. Issue 5: Database Connection Errors
Symptoms:
-
“Could not connect to database” during setup
Causes:
-
Wrong hostname, username, or password
-
MySQL service not running
-
User lacks CREATE privileges
Solutions:
-
Verify MySQL service with
systemctl status mysql
-
Check credentials in Dolibarr installer
-
Grant privileges:
GRANT ALL ON dolibarr.* TO 'user'@'localhost' IDENTIFIED BY 'password';
8. Issue 6: Incomplete Installation Wizard
Symptoms:
-
Setup gets stuck or reloads the same step
Causes:
-
PHP session or cache issue
-
Browser or server timeout
Solutions:
-
Clear browser cookies and restart the installation
-
Increase PHP timeout in
php.ini
:max_execution_time = 120
-
Use a different browser
9. Issue 7: install.lock Not Created
Symptoms:
-
Installer runs even after installation is complete
Causes:
-
Web server user lacks permission to create
install.lock
Solutions:
-
Manually create
/htdocs/install.lock
-
Set permissions:
touch install.lock && chmod 644 install.lock
-
Confirm file is readable by the web server
10. Issue 8: Conf.php File Not Writable
Symptoms:
-
“conf.php cannot be written” error
Causes:
-
File not writable during setup
Solutions:
-
Set
conf.php
to writable:chmod 666 htdocs/conf/conf.php
-
After installation, set it back to read-only:
chmod 444 conf.php
11. Issue 9: Apache or Nginx Configuration Errors
Symptoms:
-
403 Forbidden or 404 Not Found errors
Causes:
-
Misconfigured virtual host or missing rewrite rules
Solutions:
-
Verify DocumentRoot and Directory settings in
apache2.conf
-
Enable mod_rewrite:
a2enmod rewrite
-
Add
AllowOverride All
to Apache config -
For Nginx, ensure
try_files $uri $uri/ /index.php?$query_string;
is used
12. Issue 10: URL Rewrite and .htaccess Issues
Symptoms:
-
Friendly URLs not working
-
Menu links broken
Causes:
-
mod_rewrite
not enabled or.htaccess
ignored
Solutions:
-
Enable Apache’s
mod_rewrite
-
Allow
.htaccess
overrides inDirectory
config -
Test with:
http://yourdomain/dolibarr/admin/index.php
(direct URL)
13. Issue 11: Timeouts During Installation
Symptoms:
-
Installation process takes too long and fails
Causes:
-
Slow database
-
PHP execution timeout
Solutions:
-
Increase
max_execution_time
andmemory_limit
inphp.ini
-
Monitor server load and optimize MySQL
14. Issue 12: Language Pack Installation Failures
Symptoms:
-
Language selection fails or errors appear
Causes:
-
Internet connectivity or file permission issues
Solutions:
-
Download packs manually from Dolibarr translation portal
-
Extract them into
/htdocs/langs/
-
Verify correct folder names (e.g.,
fr_FR
,en_US
)
15. Issue 13: HTTPS or SSL Errors
Symptoms:
-
Browser warns about insecure connection
-
Some links not working under HTTPS
Causes:
-
SSL not properly configured
Solutions:
-
Install SSL certificate (Let’s Encrypt, etc.)
-
Update Dolibarr’s URL in conf.php to
https://
-
Force HTTPS redirection in
.htaccess
16. Issue 14: Problems with Shared Hosting Environments
Symptoms:
-
Limited PHP version or extensions
-
Permission errors
Causes:
-
Hosting provider restrictions
Solutions:
-
Choose a provider with support for custom PHP settings
-
Use
.user.ini
or.htaccess
to set PHP values -
Opt for a VPS or cloud server for full control
17. Issue 15: Reinstallation Loop
Symptoms:
-
Installation wizard restarts after completion
Causes:
-
Session lost or install.lock missing
Solutions:
-
Clear browser cookies
-
Verify
install.lock
exists and is readable -
Double-check file system path in config
18. Tools to Help Troubleshoot Installation Problems
-
phpinfo()
for PHP environment details -
Apache/Nginx error logs
-
MySQL logs:
/var/log/mysql/error.log
-
Browser developer tools (Console and Network tabs)
19. Best Practices to Prevent Installation Errors
-
Read Dolibarr’s installation guide carefully
-
Use staging servers for testing
-
Keep system packages updated
-
Monitor server resources
-
Document your installation steps and configs
20. Conclusion
Installing Dolibarr is a straightforward process when system requirements and permissions are met. However, overlooking small configurations can lead to frustrating errors. This guide provides comprehensive solutions to the most common installation issues so you can move from setup to productivity without delays. Proper planning, permissions, and system compatibility are the pillars of a successful deployment.