How to Install EspoCRM: Complete Setup Guide for Beginners 2025

This guide comprehensively explains the steps required to install EspoCRM on an Ubuntu-based server. It includes additional details and troubleshooting tips to ensure a smooth installation process.

Introduction

EspoCRM is an open-source CRM platform offering tools for managing customer relationships, sales, and marketing processes. It is highly customizable, making it suitable for businesses of all sizes. This guide focuses on installing EspoCRM on Ubuntu 20.04 or 24.04 using Apache, MySQL, and PHP.

Prerequisites

Ensure your system meets the following requirements:

• Operating System: Ubuntu 20.04 or 24.04
  
• Web Server: Apache
  
• Database: MySQL 5.7 or later
  
• PHP Version: PHP 8.2 – 8.4 (or PHP 7.4 for older systems)
  
• Non-root User: A user with sudo privileges
  

Prerequisites

Before installing EspoCRM, ensure that you have the following installed on your system:

Ubuntu
Apache
MySQL 5.7 (and later)
PHP 8.2 – 8.4

Step 1: Clone the EspoCRM Repository

git clone: paste your URL

cd espocrm

Step 2: Install Dependencies

Run the following commands to install the necessary dependencies:

npm install
npm run postinstall
npm run build
composer install

Step 3: Check Required PHP Extensions

Ensure the following PHP extensions are installed:

• pdo_mysql
• gd
• mbstring
• json
• zip
• curl
• xml
• intl
• bcmath

To install missing extensions, run:

sudo apt update

sudo apt install php-mbstring php-xml php-curl php-zip php-bcmath php-intl php-gd php-mysql
sudo systemctl restart apache2

Step 4: Ensure the Database is Running

EspoCRM requires MySQL. Check if your database is running:

sudo systemctl status mysql

If it is not running, start it with:

sudo systemctl start mysql

Step 4.1: Create a Database

Connect to MySQL and create a database for EspoCRM:

mysql -u root -p

Then, run the following commands in the MySQL shell:

CREATE DATABASE espocrm;
CREATE USER 'espocrmuser'@'localhost' IDENTIFIED BY 'yourpassword';
GRANT ALL PRIVILEGES ON espocrm.* TO 'espocrmuser'@'localhost';
FLUSH PRIVILEGES;
EXIT;

Ensure the database credentials are correctly set up in data/config.php or config-internal.php.

Example ➖

'database' => [
    'host' => 'localhost',
    'port' => '3306',  // Default MySQL port but check in your database
    'charset' => 'NULL',  // you can use this also 'utf8mb4'
    'dbname' => 'yourdatabasename', // Example: 'espocrm'
    'user' => 'databaseusername', // Example: 'espocrmuser'
    'password' => 'yourpassword',
    'platform' => 'Mysql'
]

Step 5: Configure Apache

Create a new virtual host file for EspoCRM:

sudo vim /etc/apache2/sites-available/espocrm.conf

Add the following content:

<VirtualHost *:8080>
    ServerName localhost
    DocumentRoot /home/microcosmworks/Desktop/espo
    <Directory /home/microcosmworks/Desktop/espo/espocrm>
        AllowOverride All
        Require all granted
    </Directory>

    ErrorLog ${APACHE_LOG_DIR}/espocrm_error.log
    CustomLog ${APACHE_LOG_DIR}/espocrm_access.log combined
</VirtualHost>

Ensure that DocumentRoot and <Directory> paths are correctly set according to your installation path.

Step 5.1: Update Apache Ports Configuration

Edit the ports configuration file:

sudo nano /etc/apache2/ports.conf

Ensure the following lines exist:
Listen 80
Listen 8080
<IfModule ssl_module>
        Listen 443
</IfModule>
<IfModule mod_gnutls.c>
        Listen 443
</IfModule>

Ensure that the port settings match your VirtualHost configuration 

Ex :- (Listen 8080).

Step 5.2: Enable the Site Configuration

Run the following commands:

sudo a2ensite espocrm.conf
sudo a2dissite 000-default.conf
sudo systemctl restart apache2

Step 6: Install EspoCRM

Open your browser and navigate to:

http://localhost:8080/espocrm/install/

Error: “The installation is disabled. It can be enabled in config files.”

If you encounter this error, update the following files:

Edit data/config-internal.php:

'isInstalled' => false,

Edit install/config.php:

‘isInstalled’ => false,

After making these changes, restart Apache:

sudo systemctl restart apache2

Now, proceed with the installation in your browser. Follow the on-screen instructions to set up EspoCRM.

Troubleshooting Common Issues

Error: “The installation is disabled”

• Edit data/config-internal.php and set ‘isInstalled’ => false.
  
• Restart Apache after changes.
  

Permissions Issue Ensure correct ownership and permissions for EspoCRM files:

sudo chown -R www-data:www-data /var/www/html/espocrm/

sudo chmod -R 755 /var/www/html/espocrm/

Database Connection Failure Verify database credentials in config.php or config-internal.php.

Conclusion

By completing this guide, you have successfully installed EspoCRM on your Ubuntu server, ready to manage customer interactions effectively. For further customization or troubleshooting, refer to EspoCRM’s official documentation or community forums for support.