ssossossosso
Documentation Home »The Oro Book »Installation and Configuration
2.3 version

Installation and Configuration

This article describes how to install the OroPlatform application or the OroCRM application. Both applications are similar, but the platform contains only a subset of all bundles available in the full CRM. Follow the with the link, to see the full list of bundles available in the packages.

The next steps assume that you are to install the complete OroCRM application and provide details of what has to be done differently when installing the Platform application.

Prerequisites

Please check that all the system requirements are met.

Composer

OroCRM uses Composer to manage package dependencies. We recommend to install it globally. Symfony documentation provides detailed instructions on installing Composer globally.

Hint

If Composer has been installed globally, it is enough to type composer in the console, in order to execute it.

Step 1. Get the Source Code and Define Dependencies

First, you need to obtain the application’s source code and define the dependencies. There are two ways to do so:

1a. Clone the GitHub repository and run the composer install command.

1b. Download the source code archive and run the composer update command.

1a. Clone the GitHub Repository

  1. Go to the directory, to which you want to save the OroCRM folder ([$folder_location]).

  2. Use the git clone command. Specify the version to download (in the example, it is “2.1”).

    $ cd [$folder_location]
    $ git clone -b 2.1 https://github.com/orocrm/crm-application.git orocrm
    

    Hint

    Along with 2.1, you can use any other released version or even the master branch to run the latest development version of the OroCRM.

    Tip

    Get Source Code for the OroPlatform Application

    If you are installing the Platform application, use the Platform application repository URL :

    $ cd [$folder_location]
    $ git clone -b 2.1 https://github.com/orocrm/platform-application.git orocrm
    
  3. Go to the orocrm directory and run the composer install command, in order to install the dependencies. You need to define the --prefer-dist --no-dev parameter, as otherwise you can get an error or all the development environment will be installed:

    $ cd orocrm
    $ composer install --prefer-dist --no-dev
    
  4. At the end of the composer install command, you will be asked to enter some configuration parameters in the console. The parameters are required to bootstrap the application.

    If you enter nothing, the default values (in brackets) will be used:

    Creating the "app/config/parameters.yml" file
    Some parameters are missing. Please provide them.
    database_driver (pdo_mysql):
    database_host (127.0.0.1):
    database_port (null):
    database_name (oro_crm):
    database_user (root):
    database_password (null):
    mailer_transport (smtp):
    mailer_host (127.0.0.1):
    mailer_port (null):
    mailer_encryption (null):
    mailer_user (null):
    mailer_password (null):
    websocket_bind_address (0.0.0.0):
    websocket_bind_port (8080):
    websocket_frontend_host ('*'):
    websocket_frontend_port (8080):
    websocket_backend_host ('*'):
    websocket_backend_port (8080):
    session_handler (session.handler.native_file):
    locale (en):
    secret (ThisTokenIsNotSoSecretChangeIt):
    installed (null):
    assets_version (null):
    assets_version_strategy: time_hash
    
    • The database_ parameters are used to connect to the database.

    • The mailer_ parameters define settings used to deliver emails sent by the application.

    • The websocket_ parameters define settings for the web UI.

    • The session_handler value specifies the PHP session handler to be used.

    • The locale value is the fallback locale used as a last resort for translations.

    • The secret value is used to generate CSRF tokens.

    • The assets_version parameter is used to bust the cache on assets by globally adding a query parameter to all rendered asset paths.

    • The assets_version_strategy value defines the strategy used to generate the global assets version. The available values are:

      null

      The asset’s version stays unchanged.

      time_hash

      A hash of the current time.

      incremental

      The next asset’s version is the previous version incremented by one (e.g. ver1 -> ver2 or 1 -> 2).

Hint

You can change the parameters in the “app/config/parameters.yml” file.

Note

The port used in Websocket must be open in firewall for outgoing/incoming connections

1b. Download the Source Code Archive

  1. Download the latest OroCRM version from the download section on orocrm.com.

    For example, on a Linux based OS this can be done as follows:

    $ cd [$folder_location]
    $ wget -c https://www.orocrm.com/downloads/crm-application.tar.gz
    $ tar -xzvf crm-application.tar.gz
    
  2. Run the composer install command with --prefer-dist --no-dev parameter to update the downloaded libraries to the latest supported versions (The source code archive contains all the required libraries. They will be installed to the vendor directory):

    $ cd orocrm
    $ composer install --prefer-dist --no-dev
    
  3. Update the configuration parameters if necessary.

    Unlike when downloading from the GitHub repository, you won’t be asked to define the parameters in the console, and default values will be used instead. If any of the parameters need to be changed, do this manually afterwards in the app/config/parameters.yml file.

Step 2. Create the Database

Create an empty database, such that its values correspond to the configuration parameters starting with database_.

Note

Using MySQL 5.X on HDD is potentially risky because of performance issues. Recommended configuration for this case is:

1
2
innodb_file_per_table = 0
wait_timeout = 28800

See also

See optimizing InnoDB Disk I/O for more information.

Note

Using PostgreSQL, you need to load uuid-ossp extension to ensure proper doctrine’s guid type handling. Log into database and run sql query:

CREATE EXTENSION "uuid-ossp";

Step 3. Web Server Configuration

For Apache 2.2, configure the server as follows:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
<VirtualHost *:80>
    ServerName orocrm.example.com

    DirectoryIndex app.php
    DocumentRoot [$folder_location]}/orocrm/web
    <Directory  [$folder_location]}/orocrm/web>
        # enable the .htaccess rewrites
        AllowOverride All
        Order allow,deny
        Allow from All
    </Directory>

    ErrorLog /var/log/apache2/orocrm_error.log
    CustomLog /var/log/apache2/orocrm_access.log combined
</VirtualHost>

For Apache 2.4, configure the server as follows:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
<VirtualHost *:80>
    ServerName orocrm.example.com

    DirectoryIndex app.php
    DocumentRoot [$folder_location]}/orocrm/web
    <Directory  [$folder_location]}/orocrm/web>
        # enable the .htaccess rewrites
        AllowOverride All
        Require all granted
    </Directory>

    ErrorLog /var/log/apache2/orocrm_error.log
    CustomLog /var/log/apache2/orocrm_access.log combined
</VirtualHost>

Note

Please make sure mod_rewrite and mod_headers are enabled.

For Nginx, the virtual host configuration should look as follows:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
server {
    server_name orocrm.example.com;
    root  [$folder_location]}/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 127.0.0.1:9000;
        # or
        # fastcgi_pass unix:/var/run/php/php7-fpm.sock;
        fastcgi_split_path_info ^(.+\.php)(/.*)$;
        include fastcgi_params;
        fastcgi_param SCRIPT_FILENAME $document_root$fastcgi_script_name;
        fastcgi_param HTTPS off;
    }

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

Caution

Make sure that the web server user has permissions for the log directory of the application.

More details on the file permissions configuration are available in the official Symfony documentation

PHP-FPM Configuration, the example of the PHP-FPM configuration is the following:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
[www]
listen = 127.0.0.1:9000
; or
; listen = /var/run/php/php7-fpm.sock

listen.allowed_clients = 127.0.0.1

pm = dynamic
pm.max_children = 128
pm.start_servers = 8
pm.min_spare_servers = 4
pm.max_spare_servers = 8
pm.max_requests = 512

catch_workers_output = yes

Note

Make sure that options fastcgi_pass for Nginx and listen for PHP-FPM are configured accordingly.

PHP Optimization, please install Opcache php-extention. Here is a configuration example:

zend_extension=opcache.so
opcache.enable=1
opcache.memory_consumption=256
opcache.interned_strings_buffer=8
opcache.max_accelerated_files=11000
opcache.fast_shutdown=1
opcache.load_comments=1
opcache.save_comments=1

Note

The opcache.load_comments and opcache.save_comments parameters are enabled by default and should remain so for Oro application operation. Please do not disable them.

Multiple PHP Versions

If you have multiple PHP versions installed, you should configure which of these binaries the application will use when executing CLI commands:

For Apache

When using Apache, use the SetEnv directive to set the value for the “ORO_PHP_PATH” environment variable:

SetEnv ORO_PHP_PATH c:\OpenServer\modules\php\PHP-7.0\

For Nginx

With Nginx, you have to use the fastcgi_param option to achieve the same:

fastcgi_param ORO_PHP_PATH /usr/local/bin/php

Step 4. Add “orocrm.example.com” to the “hosts” or “DNS” file

Add the “orocrm.example.com” hostname to your DNS or hosts file.

For example, your “/etc/hosts” file on a Linux system may look like this:

127.0.0.1 orocrm.example.com

Step 5. Run the Installation Script and Launch the Application

Now, you can run the installation script which checks your system requirements, performs migrations and sets up the database tables. – You can run the install script in two ways:

5a. Use the installation wizard in a web browser.

5b. Run the console installation command.

While the use of the installation wizard is easier and more straightforward, running installation from the console provides some additional flexibility as described in the relevant section below.

5a. Start the Wizard

  1. Check System Requirements

    • Click the Begin installation button.

    • The installation wizard will check the system configuration:

    • Fix any issues that have been discovered and refresh the page.

    • When your system configuration meets the OroCRM requirements, click Next.

  2. Configuration

    • In the emerged page, specify the application configuration. The values defined in the configuration parameters will be filled in automatically, but they can be changed.

    • When all the settings are correct, click Next.

  3. Database Initialization

    The database initialization will start automatically, as soon as you have clicked Next at the end of the previous step:

    Hint

    If something goes wrong and a failure occurs, you can check error logs in the app/logs/oro_install.log file. Fix the errors, click the Back button and repeat.

  4. Administration Setup

    • Define the administrative data such as the company name and administrator’s credentials:

    • Check the “Load Sample Data” box if you need the Sample Data.

    • Click the Install button.

  5. Finalization

    The installation will head for completion, as soon as you have clicked Install at the end of the previous phase.

    Hint

    If something goes wrong and a failure occurs, you can check error logs in the orocrm/app/logs/oro_install. Fix the errors, click Back button and repeat.

  6. Launch the Application

    • The “Finish” page will appear

    • Click Launch Application and enjoy OroCRM capabilities for your business.

5b. Using the Installation Command

Another way to run the installation script is with the oro:install command in the console.

Warning

To avoid access permissions issues, please review the Symfony Setting up or Fixing File Permissions guide before running any commands. On top of that, consider running the command(s) below with sudo -u [web server user name] prefix.

The “–env=prod” parameter must be defined, as otherwise the development environment will be installed.

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

The Installation is a four step process:

  1. The system requirements are checked. The setup process terminates if any of the requirements are not fulfilled.
  2. The database and all caches are reset.
  3. The initial data (i.e. migrations, workflow definitions and fixture data) are loaded and executed.
  4. The assets are dumped, RequireJS is initialized.

If you invoke the command without any arguments, you will be asked to enter some values for certain configuration options:

Option Description
--company-short-name Company short name
--company-name Company name
--user-name User name
--user-email User email
--user-firstname User first name
--user-lastname User last name
--user-password User password
--sample-data Determines whether sample data need to be loaded or not

If the system configuration doesn’t meet the requirements, the install command will notify you about it. Fix the issues and run the command once again.

If other problems occur, you can see the details in app/logs/oro_install.log file.

Hint

Normally, the installation process is terminated if it detects an already-existing installation. Use the “–force” option to overwrite an existing installation, e.g. during your development process.

Hint

After the installation finished do not forget to run php app/console oro:api:doc:cache:clear to warm-up the API documentation cache. This process may take several minutes.

Customizing the Installation Process

You can customize the installation process in several ways:

Execute Custom Migrations

You can create your own migrations that can be executed during the installation. A migration is a class which implements the Migration interface:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
// src/Acme/DemoBundle/Migration/CustomMigration.php
namespace Acme\DemoBundle\Migration;

use Doctrine\DBAL\Schema\Schema;
use Oro\Bundle\MigrationBundle\Migration\Migration;
use Oro\Bundle\MigrationBundle\Migration\QueryBag;

class CustomMigration implements Migration
{
    public function up(Schema $schema, QueryBag $queries)
    {
        // ...
    }
}

In the up(), you can modify the database schema and/or add additional SQL queries that are executed before and after the schema changes.

The MigrationsLoader dispatches two events when migrations are being executed, oro_migration.pre_up and oro_migration.post_up. You can listen to either event and register your own migrations in your event listener. Use the addMigration() method of the passed event instance to register your custom migrations:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
// src/Acme/DemoBundle/EventListener/RegisterCustomMigrationListener.php
namespace Acme\DemoBundle\EventListener;

use Acme\DemoBundle\Migration\CustomMigration;
use Oro\Bundle\MigrationBundle\Event\PostMigrationEvent;
use Oro\Bundle\MigrationBundle\Event\PreMigrationEvent;

class RegisterCustomMigrationListener
{
    // listening to the oro_migration.pre_up event
    public function preUp(PreMigrationEvent $event)
    {
        $event->addMigration(new CustomMigration());
    }

    // listening to the oro_migration.post_up event
    public function postUp(PostMigrationEvent $event)
    {
        $event->addMigration(new CustomMigration());
    }
}

Tip

You can learn more about custom event listeners in the Symfony documentation.

Migrations registered in the oro_migration.pre_up event are executed before the main migrations while migrations registered in the oro_migration.post_up event are executed after the main migrations have been processed.

Load Custom Data Fixtures

To load your own data fixtures, you’ll need to implement Doctrine’s “FixtureInterface”:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
// src/Acme/DemoBundle/Migrations/Data/ORM/CustomFixture.php
namespace Acme\DemoBundle\Migrations\Data\ORM;

use Doctrine\Common\DataFixtures\FixtureInterface;
use Doctrine\Common\Persistence\ObjectManager;

class CustomFixture implements FixtureInterface
{
    public function load(ObjectManager $manager)
    {
        // ...
    }
}

Caution

Your data fixture classes must reside in the “Migrations/Data/ORM” sub-directory of your bundle to be loaded automatically during the installation.

Tip

Read the documentation to learn more about the Doctrine Data Fixtures extension.

Activating Background Tasks

To launch scheduled execution of the operations required by the Oro application, set up a cron command with the oro:cron CLI command as an application entry point (see the sample configuration below).

*/1 * * * * /path/to/php [$folder_location]/orocrm/app/console oro:cron --env=prod > /dev/null

See also

You can also create your own commands that are executed in the background at certain times. Read more about it in the chapter about executing cron commands.

Time consuming or blocking tasks should usually be performed in the background to aviod negative impact on the application response time. For example, the OroPlatform uses the MessageQueueComponent together with MessageQueueBundle to asynchronously run maintenance tasks. Ensure that one or more consumers are always running:

/path/to/php [$folder_location]/orocrm/app/console oro:message-queue:consume --env=prod > /dev/null

See also

To ensure that required number of consumers keeps running, set up a supervisor. Here is example of supervisord configuration.

Updating OroPlatform to OroCRM

If are not sure whether or not you need the full OroCRM application, you can start with the OroPlatform application and upgrade it by installing the “oro/crm” package using Composer:

$ composer require oro/crm
Browse maintained versions:
current1.102.02.32.4