How to Install OroCRM on Ubuntu 20.04

OroCRM is a customer relationship management software. It is a simple and low-cost CRM system ideal for small and medium-sized enterprises.

OroCRM is an integrated CRM, marketing automation, and live chat platform that helps marketers build genuine relationships with their prospects and customers. It has all the features to create, manage, measure, and optimize customer journeys. OroCRM streamlines the management of large amounts of data to provide accurate insights for better decision-making.

The software offers a great set of features, which can be customized to suit the needs of any size company. It also comes at an affordable price, perfect for startup companies.

OroCRM is designed with simplicity in mind, making it super easy to use for beginners and experts alike.

Prerequisites

• A Vultr Ubuntu 20.04 server instance.
• A non-root user with sudo permission.

In this tutorial, we will use orocrm.example.com for the installation domain, so you should change it with your desired domain for your installed OroCRM.

Update Your System

Before starting OroCRM installation on your Ubuntu 20.04 system, update your system and ensure your system packages are up-to-date.

To update and upgrade the system package, use the following commands:

$ sudo apt-get update

$ sudo apt-get upgrade

Install Nginx and PHP 7

OroCRM can run with any web server which is supporting PHP. The new version of OroCRM supports all PHP versions greater than 7.0. This tutorial will show you to install OroCRM using Nginx web server with PHP 7.4 and php-fpm.

Install Nginx

After updating the system package, use the following command to install Nginx web server in your Ubuntu 20.04 system:

$ sudo apt -y install nginx

After successful installation of Nginx, you can use the following command to start the webserver and enable it for an auto-start on system boot:

$ sudo systemctl start nginx

$ sudo systemctl enable nginx

Install PHP

To install PHP's latest compatible version in your system, first, add PHP's Ondrej repository. You can use the following command to add and enable PHP repository in your Ubuntu system:

$ sudo apt install software-properties-common

$ sudo add-apt-repository ppa:ondrej/php

After adding the repository you can execute the following command to install php7.4 and all php extension dependencies:

$ sudo apt update

$ sudo apt -y install php7.4 php7.4-fpm php7.4-common php7.4-curl php7.4-gd php7.4-intl php7.4-json php7.4-mbstring php7.4-mcrypt php7.4-mysql php7.4-xml php7.4-xml php7.4-zip php7.4-tidy php7.4-soap php7.4-opcache

Now, edit the installed PHP configuration file:

$ sudo vim /etc/php/7.4/cli/php.ini

Find the below lines in the configuration file, uncomment and make changes parameters as shown; you can use your timezone:

date.timezone = Asia/Kolkata

;Replace "Asia/Kolkata" with your appropriate timezone

cgi.fix_pathinfo=0

Now, after installation and configuration of php7.4 in our system, start the php7.4-fpm and enable it to run automatically on system boot using the following commands:

$ sudo systemctl start php7.4-fpm

$ sudo systemctl enable php7.4-fpm

Now that the webserver and PP have been installed in your system, let us install and configure Database for OroCRM using MariaDB.

Install MariaDB

MariaDB is a drop-in replacement for MySQL and is available in most Linux distributions, including Red Hat Enterprise Linux (RHEL), CentOS, Debian, Fedora, Oracle Linux, OpenSUSE, and Ubuntu. MariaDB provides more features than MySQL, such as JSON support and improved performance.

In Ubuntu 20.04 MariaDB's version 10.3 is included, so you can install it by using the following command:

$ sudo apt update

$ sudo apt install mariadb-server

After successfully installing MariaDB, the service will start automatically. You can verify that the MariaDB server is running using the following command:

$ sudo systemctl status mariadb

Output:

● mariadb.service - MariaDB 10.3.22 database server

     Loaded: loaded (/lib/systemd/system/mariadb.service; enabled; vendor preset: enabled)

     Active: active (running) since Wed 2021-12-01 16:52:07 UTC; 12s ago

     ...

After installation of MariaDB server in the system, enable it to run automatically on system boot using the following commands:

$ sudo systemctl enable MariaDB

Now, MariaDB is installed in your system to create a database and user for OroCRM.

Create a Database for OroCRM

First, login to the MariaDB shell as root user by running:

$ mysql -u root -p

It will ask the root user's password to get into the MariaDB shell.

Now, run the following commands to create a database and database user for OroCRM installation:

CREATE DATABASE oro_crm; 

CREATE USER 'oro_user'@'localhost' IDENTIFIED BY 'OroPassword'; 

GRANT ALL PRIVILEGES ON oro_crm.* TO 'oro_user'@'localhost'; 

FLUSH PRIVILEGES; 

EXIT;

You can choose the database and user name as per your requirement; here, we use oro_crm as database name and oro_user as the database user to access the database from the application. 

Install Node.js and Composer

OroCRM uses JavaScript runtime for the user interface, requiring Node.js to compile JavaScript to build the user interface.

Install Node.js

The default repository of the Ubuntu system has an outdated or old version of Node.js, so you should add the Nodesource repository to the system to install the latest version of Node.js.

You can add a Nodesource repository to your Ubuntu system using the following command: 

$ sudo curl --silent --location https://deb.nodesource.com/setup_16.x | sudo bash -

After adding the repository, use the following command to install node.js:

$ sudo apt install nodejs

Once node.js et installed in your system, you can verify it by checking the installed version of Node.js:

 $ node -v

Output

v16.6.1

Install Git

OroCRM's repository or package is available on Github, so we also need Git to clone OroCRM files into the system.

To install Git into your system, run the following command:

$ sudo apt -y install git

Install Composer

The OroCRM application is developed in PHP, so we need a composer to install OroCRM.

To install a composer into the Ubuntu system, use the following command:

$ php -r "copy('https://getcomposer.org/installer', 'composer-setup.php');"

$ php composer-setup.php

By Default, the composer binary file will be available on the current directory, so you can move it on /usr/bin directory to execute composer from any location of the system by anyone:

$ sudo mv composer.phar /usr/bin/composer

 Provide execution permission to the composer:

$ sudo chmod +x /usr/bin/composer

Install OroCRM

There are several options to download OroCRM to your server, but it's better to get it from Github. The most updated version is available to clone through Git.

To clone the OroCRM repository, use the following commands:

$ cd /usr/share/nginx/

$ sudo git clone -b 2.4 https://github.com/oroinc/crm-application.git orocrm

Copy sample parameters file to make it a default parameter setting file used by OroCRM:

$ cd orocrm

$ sudo cp app/config/parameters.yml.dist app/config/parameters.yml

Now, it's time to update the parameters.yml file to provide database and email configuration for OroCRM application:

$ sudo vim app/config/parameters.yml

Find the following lines in the file:

database_driver: pdo_mysql 

database_host: 127.0.0.1 

database_port: ~ 

database_name: oro_crm 

database_user: root 

database_password: ~

Update these configuration parameters according to the database you have created above to store all OroCRM data. In our case, it should look like this:

database_driver: pdo_mysql 

database_host: 127.0.0.1 

database_port: 3306 

database_name: oro_crm 

database_user: oro_user 

database_password: OroPassword

If you have an SMTP server configuration to use in OroCRM, you can update the mailer setting with mailer parameters shown as below:

mailer_transport: smtp 

mailer_host: mail.example.com 

mailer_port: 456 

mailer_encryption: ssl 

mailer_user: mails@example.com 

mailer_password: EMailPassword

 If you don't have a mail server ready, you can leave these settings with existing values. You can always change these settings in the future whenever you have a mail server configuration.

You should set a random string for secret by replacing ThisTokenIsNotSoSecretChangeIt. This random string is used to encode the session data for OroCRM. For example, the random string can look like this:

secret: ctvpXHhFyCFc9yU1hV1fMwjSoyZYzGh4WBMBBBa3XEgrRUF5OuB2h8iNl9JRMpt

 To get a good random string, you can use the pwgen utility to generate it.

You can install pwgen in your Ubuntu system using the following command:

$ sudo apt -y install pwgen

To generate a random string using pwgen running:

pwgen -s 64 1

 After completing the OroCRM configuration, save the file and exit the editor.

Now, you can install the PHP dependencies for the application using composer as shown below:

$ sudo composer install --prefer-dist --no-dev

It would be best to use the option: no-dev, to ensure that the composer will install all dependencies to run the application in production mode. Depending upon your servers and network speed, it will take a few minutes to download and install the required Php dependencies.

Once the composer has installed all dependencies, you are ready to install OroCRM using the following command:

$ sudo php app/console oro:install --env=prod

 The installation of OroCRM will only proceed after all required dependencies are installed and configured. It will build the web cache and write a database to use in the application. The –env-prod option used in command will install the application in production mode.

In the process of installation, you will be asked a few questions to configure an administrator account, which is as follows:

Administration Setup

Application URL (http://localhost): http://orocrm.example.com 

Organization name (OroCRM): My Org 

Username (admin): admin 

Email: mail@example.com 

First name: Mark 

Last name: Down 

Password: 

Load sample data (y/n): y

After filing the above information and giving confirmation to load sample data, it will write sample data into the database. This can help you understand the application better, however, before using it in production, it's good to erase sample data.

Use the following command to warm up the API documentation cache:

$ sudo php app/console oro:api:doc:cache:clear

Configuring Nginx

To configure Nginx web server for an application, the first step is to create an Nginx server block file:

$ sudo vim /etc/nginx/sites-available/orocrm

Add the following setting in the file:

server {
 server_name orocrm.example.com;
 root /usr/share/nginx/orocrm/web;

 location / {
   # try to serve file directly, fallback to app.php
   try_files $uri /app.php$is_args$args;
 }
 location ~ ^/(app|app_dev|config|install)\.php(/|$) {
   fastcgi_pass unix:/run/php/php7.4-fpm.sock;
   fastcgi_split_path_info ^(.+\.php)(/.*)$;
   include fastcgi_params;
   fastcgi_param SCRIPT_FILENAME $document_root$fastcgi_script_name;
   fastcgi_param HTTPS off;
 }
 # Enable Gzip compression
 gzip on;
 gzip_buffers 16 8k;
 gzip_comp_level 5;
 gzip_disable "msie6";
 gzip_min_length 1000;
 gzip_http_version 1.0;
 gzip_proxied any;
 gzip_types text/plain application/javascript application/x-javascript text/javascript text/xml text/css image/svg+xml;
 gzip_vary on;    

 # Enable browser caching
 # One week for javascript and css
 location ~* \.(?:css|js) {
   expires 1w;
   access_log off;
   add_header Cache-Control public;
 }

 # Three weeks for media: images, fonts, icons, video, audio etc.
 location ~* \.(?:jpg|jpeg|gif|png|ico|tiff|woff|eot|ttf|svg|svgz|mp4|ogg|ogv|webm|swf|flv)$ {
   expires 3w;
   access_log off;
   add_header Cache-Control public;
 }

 error_log /var/log/nginx/orocrm_error.log;
 access_log /var/log/nginx/orocrm_access.log;

}

 In this configuration file, the application domain is orocrm.example.com, so make sure you change the domain with your domain. The above Nginx configuration is included GZip compression and browser caching. It is useful to load applications fast in the browser. The browser caching helps to store static resources to the browser in the client system. So, in the user access site, most of the static content is loaded from its cache.

Now you can enable Nginx newly configured site:

$ sudo ln -s /etc/nginx/sites-available/orocrm /etc/nginx/sites-enabled/orocrm

You can check the Nginx configuration for any error by running:

$ sudo nginx -t

You will get the output similar to below:

user@vultr:/usr/share/nginx/orocrm$ sudo nginx -t

nginx: the configuration file /etc/nginx/nginx.conf syntax is ok

nginx: configuration file /etc/nginx/nginx.conf test is successful

You should give ownership of OroCRM application to the Nginx user with the following command: 

$ sudo chown -R www-data:www-data /usr/share/nginx/orocrm

Restart Nginx to apply the new configuration:

$ sudo systemctl restart nginx

Now, the OroCRM application is accessible at http://orocrm.example.com. You can log in using your administrator username and password you have configured during installation.

Setup Cron and Background Jobs

To run scheduled tasks automatically, you should use the Cron job. To add cron job open crontab:

$ sudo crontab -e

Add the following line or job into the file:

*/1 * * * * /usr/bin/php /usr/share/nginx/orocrm/app/console oro:cron --env=prod > /dev/null

 The above job will run every minute, so any scheduled task such as email queues is processed fast.

You need a Supervisor to run the Message Queue service in your system.

A Supervisor is a message queue service that helps you manage your tasks. It also helps you organize the sequence in which the tasks are completed.

Install Supervisor

 To install supervisor, use the following command:

$ sudo apt -y install supervisor

 Create a new supervisor configuration file:

$ sudo vim /etc/supervisor/conf.d/orocrm.conf

Add the following configuration to your newly created configuration file:

[program:oro_message_consumer]

command=/usr/bin/php /usr/share/nginx/orocrm/app/console --env=prod --no-debug oro:message-queue:consume
process_name=%(program_name)s_%(process_num)02d
numprocs=4
autostart=true
autorestart=true
startsecs=0
user=www-data
redirect_stderr=true

 Use the following commands to restart the Supervisor and enable it to start on system boot automatically.

$ sudo systemctl restart supervisor

$ sudo systemctl enable supervisor

You can check supervisor processes running status using the following command:

$ sudo supervisorctl status

If the processes are running without a problem, you will get a running status similar to this:

user@vultr:/usr/share/nginx/orocrm$ sudo supervisorctl status

oro_message_consumer:oro_message_consumer_00 RUNNING  
pid 20809, uptime 0:00:01

oro_message_consumer:oro_message_consumer_01 RUNNING  
pid 20808, uptime 0:00:01

oro_message_consumer:oro_message_consumer_02 RUNNING  
pid 20807, uptime 0:00:01

oro_message_consumer:oro_message_consumer_03 RUNNING  
pid 20806, uptime 0:00:01

 Now OroCRM is installed in your system or server and ready to use.

Conclusion

In this tutorial, you have learned to install Nginx, Node.js, PHP Composer, Git, and most importantly, OroCRM. You also learned to install and configure supervisor for Applications.