You are browsing the documentation for version 3.1 of OroCommerce, OroCRM and OroPlatform, which is no longer maintained. Read version 5.1 (the latest LTS version) of the Oro documentation to get the updated information.
See our Release Process documentation for more information on the currently supported and upcoming releases.
Environment Setup for Community Edition
This topic provides a detailed description of the environment setup process for Community Edition of Oro applications.
Before you proceed, please refer to the System Requirements for the complete list of the recommended environmental components and their supported versions. If you are using the same environment and components, as described in the System Requirements, you can reuse the commands provided in this guide without modification. Otherwise, please adjust them to match the syntax supported by the tools of your choice.
Prepare a Server with OS
Get a dedicated physical or virtual server with at least 2Gb RAM with the CentOS v7.4 installed. Ensure that you can run processes as a root user or user with sudo permissions.
Enable Required Package Repositories
Add the EPEL repository to your yum package manager by running:
yum install -y epel-release yum update -y
Install Nginx, NodeJS, Git, Supervisor, and Wget
Install most of the required Oro application environment components using the following commands:
yum install -y nginx wget git nodejs supervisor yum-utils
As you need to install MySQL 5.7 to replace the default MariaDB replica in CentoOS, get the MySQL 5.7 package from the MySQL official repository:
wget https://dev.mysql.com/get/mysql80-community-release-el7-1.noarch.rpm && rpm -ivh mysql80-community-release-el7-1.noarch.rpm yum-config-manager --disable mysql80-community yum-config-manager --enable mysql57-community
Next, install MySQL 5.7 using the following command:
yum install -y mysql-community-server
As you need to install PHP 7.1 instead of CentOS 7 native PHP 5.6 version, get the PHP 7.1 packages from the REMI repository:
wget http://rpms.remirepo.net/enterprise/remi-release-7.rpm && rpm -Uvh remi-release-7.rpm yum-config-manager --enable remi-php71 yum update -y
Next, install PHP 7.1 and the required dependencies using the following command:
yum install -y php-fpm php-cli php-pdo php-mysqlnd php-xml php-soap php-gd php-mbstring php-zip php-intl php-mcrypt php-opcache
Run the commands below, or use another Composer installation process described in the official documentation.
php -r "copy('https://getcomposer.org/installer', 'composer-setup.php');" && php composer-setup.php php -r "unlink('composer-setup.php');" mv composer.phar /usr/bin/composer
Install Symfony Flex
To improve composer operations performance install Symfony Flex globally:
composer global require symfony/flex
Enable Installed Services
systemctl start mysqld php-fpm nginx supervisord systemctl enable mysqld php-fpm nginx supervisord
Perform Security Configuration
For the production environment, it is strongly recommended to keep SELinux enabled in the enforcing mode.
The actual SELinux configuration depends on the real production server environment and should be configured by an experienced system administrator.
In this guide, to simplify installation in the local and development environment, we are loosening the SELinux mode by setting the permissive option for the setenforce mode. However, your environment configuration may differ. If that is the case, please adjust the commands that will follow in the next sections to match your configuration.
sed -i 's/SELINUX=enforcing/SELINUX=permissive/g' /etc/selinux/config setenforce permissive
Configure Users Permissions
For security reasons, we recommend performing all Oro application-related processes on behalf of two different linux users:
- Administrative user (for example, oroadminuser) — A user should be able to perform administration operations like application installation, update, etc.
- Application user (for example, nginx) — A user should be able to perform runtime operations that require no changes in the application source code files.
In this guide, to simplify installation in the local and development environment, we are loosening this requirement and use the superuser permissions to perform Oro application administrative tasks. However, for your staging or production environment, please adjust the commands that will follow in the next sections to run environment management commands as well as application install and update via a dedicated admin user.
Commands for running the web server, php-fpm process, cron commands, background processes, etc., are executed via the dedicated application user (nginx). Reuse them without modification, if you keep the same username. Otherwise, adjust them accordingly.
Prepare MySQL Database
Change the Default MySQL Password for Root User
To find the temporary mysql root user password that was created automatically, run:
grep 'temporary password' /var/log/mysqld.log
Use this password to login to mysql CLI as root user and change the temporary password to the new secure one (we have used the P@ssword123):
mysql -uroot -p ALTER USER 'root'@'localhost' IDENTIFIED BY 'P@ssword123';
Replace P@ssword123 with your secret password. Ensure it contains at least one upper case letter, one lower case letter, one digit, and one special character, and has a total length of at least 8 characters.
Change the MySQL Server Configuration
It is recommended to use SSD to store the application data in the MySQL 5.X database. However, in case you do need to use the HDD, set the following configuration parameters in the /etc/my.cnf file to avoid performance issues:
[mysqld] innodb_file_per_table = 0 wait_timeout = 28800
To minimize the risk of long compilations of SQL queries (which sometimes may take hours or even days; for details, see MySQL documentation), set optimizer_search_depth to 0:
[mysqld] optimizer_search_depth = 0
To store supplementary characters (such as 4-byte emojis), configure the options file to use the utf8mb4 character set:
[client] default-character-set = utf8mb4 [mysql] default-character-set = utf8mb4 [mysqld] character-set-server = utf8mb4 collation-server = utf8mb4_unicode_ci
For the changes to take effect, restart MySQL server by running:
systemctl restart mysqld
Create a Database for the Application and a Dedicated Database User
Replace oro_user with a new username and P@ssword123 with a more secure password. Ensure that the password contains at least one upper case letter, one lower case letter, one digit, one special character, and has the total length of at least 8 characters.
Configure Web Server
For the production mode, it is strongly recommended to use the HTTPS protocol for the Oro application public websites, and reserve the HTTP mode for development and testing purposes only.
The samples of Nginx configuration for HTTPS and HTTP mode are provided below. Update the /etc/nginx/conf.d/default.conf file with the content that matches the type of your environment.
Sample nginx Configuration for HTTP Websites (Use in Development and Staging Environment Only)
Sample nginx Configuration for HTTPS Websites (Safe for Production Environment)
- Replace <application-root-folder> with the absolute path where you are going to install the Oro application.
- Replace <your-domain-name> with the configured domain name that would be used for the Oro application.
- Change ssl_certificate_key and*ssl_certificate* with the actual values of your active SSL certificate.
Optionally, you can enable and configure Apache PageSpeed module for Nginx to improve web page latency as described in the Performance Optimization of the Oro Application Environment article.
If you choose the Apache web server instead of Nginx one, the example of the web server configuration you can find in the Web Server Configuration article.
For the changes to take effect, restart nginx by running:
systemctl restart nginx
Configure Domain Name Resolution
If you are going to use the Oro application in the local environment only, modify the /etc/hosts file on the server by adding the following line:
127.0.0.1 localhost <your-domain-name>
After this change, the <your-domain-name> URLs opened in the local environment are handled by the local webserver.
To make your Oro application accessible from the remote locations, configure a DNS server to point your domain name to your server IP address.
To configure PHP, perform the following changes in the configuration files:
In the www.conf file (/etc/php-fpm.d/www.conf) — Change the user and the group for PHP-FPM to nginx and set recommended values for other parameters.
user = nginx group = nginx catch_workers_output = yes
In the php.ini file (/etc/php.ini) — Change the memory limit and cache configuration to the following:
memory_limit = 1024M realpath_cache_size=4096K realpath_cache_ttl=600
In the opcache.ini file (/etc/php.d/10-opcache.ini) — Modify the OPcache parameter to match the following values:
opcache.enable=1 opcache.enable_cli=0 opcache.memory_consumption=512 opcache.interned_strings_buffer=32 opcache.max_accelerated_files=32531 opcache.save_comments=1
For the changes to take effect, restart PHP-FPM by running:
systemctl restart php-fpm