Installation

en | ru

* this article is under translation

ATTENTION: These instructions are valid for ERP USERSIDE versions 3.11 and above. For versions 3.10 and below - use separate installation instructions for 3.10.

Description

For the sake of simplicity, commands for the Linux Debian 11 operating system will be considered. For experienced system administrators, it should not be difficult to use similar commands for another operating system. If you do not feel confident in the administration of operating systems, we recommend that you use either Debian or Ubuntu Server. Because of their simplicity and also because our technical support team has a much better understanding of Debian-like distributions. You are much more likely to be able to get an advise on anything not related to ERP USERSIDE, but related to the administration of the operating system, if you have Debian or a similar distribution based on it.

On the other hand, if you are an experienced system administrator and have skills and experience with Docker, it may be more convenient for you to use a ready-made environment based on the Docker images that we have specially prepared, including everything you need for ERP USERSIDE. In this case, you won't have to configure anything other than to make simple Docker bundle settings.

This instruction is repeated in its entirety on a Debian 10 test server and this process is recorded as a screencast. Maybe someone will find it useful: https://youtu.be/Zls7MA1rV6Q

Requirements

ERP USERSIDE requires various system applications and services, such as a PHP language interpreter with a set of extensions, a WEB-server, a database management system and others. This section will list such requirements depending on the ERP USERSIDE version.

Also note that your operating system must be configured with the correct time zone and locale. This determines the correctness of the information displayed and the correctness of sorting.

The list of required PHP extensions contains all extensions that are not part of the PHP core. Some of these extensions may be bundled with the main PHP package or as part of the php-common package, while others must be installed separately.

3.16, 3.17 (current stable)

• PHP: 7.2 - 7.4
• PHP extensions: ctype, gd, json, libxml, mbstring, openssl, pdo, pdo_pgsql, posix, simplexml, snmp, sockets, zlib, pcntl
• PHP optional extensions: ldap, soap
• Python: 3.7+
• Python Modules: pip, virtualenv
• PostgreSQL: 10+
• Redis: 5+
• RabbitMQ: 3.8+
• Supervisor

3.15

• PHP: 7.1 - 7.4
• PHP extensions: ctype, gd, json, libxml, mbstring, openssl, pdo, pdo_pgsql, posix, simplexml, snmp, sockets, zlib
• PHP optional extensions: ldap, soap
• PostgreSQL: 10+
• Redis: 5+

3.14

• PHP: 7.1 - 7.3
• PHP extensions: ctype, gd, json, libxml, mbstring, openssl, pdo, pdo_pgsql, posix, simplexml, snmp, sockets, zlib
• PHP optional extensions: ldap, soap
• PostgreSQL: 10+
• Redis: 5+

3.13

• PHP: 7.1 - 7.3
• PHP extensions: ctype, gd, json, libxml, mbstring, openssl, pdo, pdo_pgsql, posix, simplexml, snmp, sockets, zlib
• PHP optional extensions: ldap, soap
• PostgreSQL: 9.6+
• Redis: 5+

3.12

• PHP: 7.0 - 7.1
• PHP extensions: ctype, gd, json, libxml, mbstring, openssl, pdo, pdo_pgsql, posix, simplexml, snmp, sockets, zlib
• PHP optional extensions: ldap, soap
• PostgreSQL: 9.5+

3.11

• PHP: 5.6 - 7.1
• PHP extensions: ctype, gd, json, libxml, mbstring, openssl, pdo, pdo_pgsql, posix, simplexml, snmp, sockets, zlib
• PHP optional extensions: ldap, soap
• PostgreSQL: 9.5+
• MySQL: 5.6 - 5.7

Main Agreements

The directory where ERP USERSIDE is installed is /var/www/userside. Inside this directory must be a subdirectory userside3, which is the root directory for the WEB-server. If you want to use a different directory for ERP USERSIDE, don't forget to correct all the examples in this manual accordingly.

Create a directory:

sudo mkdir -p /var/www/userside/userside3
sudo chown -R www-data:www-data /var/www/userside

You need to allocate a domain name for ERP USERSIDE. The examples below use userside.mycompany.com, but you will need to replace it with your own.

Installing the required components

The installation will be shown for the latest current ERP USERSIDE version 3.16. For other versions, you can modify these commands yourself to get the right set of applications installed for certain versions. Also note that some components are not needed for other versions of ERP USERSIDE.

First install the utilities that will be needed later in the installation process. They are required for any ERP USERSIDE version. You can copy lines one by one and paste them into the command line of your operating system.

sudo apt update
sudo apt install -y apt-transport-https lsb-release ca-certificates curl gnupg debian-keyring debian-archive-keyring

Copy and paste the following lines entirely:

sudo tee /etc/apt/sources.list.d/contrib-non-free.list << EOL
deb http://deb.debian.org/debian/ $(lsb_release -sc) contrib non-free
deb http://deb.debian.org/debian/ $(lsb_release -sc)-updates contrib non-free
deb http://security.debian.org/debian-security $(lsb_release -sc)-updates contrib non-free
EOL

sudo apt update
sudo apt install -y libsnmp-dev snmp-mibs-downloader

PostgreSQL

Alternative official repository

To be able to always install and update to the latest version of PostgreSQL, add an alternative official repository to your operating system by running the commands:

wget --quiet -O - https://www.postgresql.org/media/keys/ACCC4CF8.asc | sudo apt-key add -
echo "deb http://apt.postgresql.org/pub/repos/apt/ $(lsb_release -sc)-pgdg main" | sudo tee -a /etc/apt/sources.list.d/pgdg.list
sudo apt update

If you have a different operating system, you can find the necessary commands for it at official PostgreSQL website.

The step of adding an alternate repository here and hereafter is optional, but only if your operating system's main repository contains packages of those versions that fall within the range required for the ERP USERSIDE version being installed.

Installation

Before you install PostgreSQL in your operating system, your local locale and the correct time zone must be set. This can also be done later, but it is easier if it is done before installation. Run the following command to make sure that the desired locale is present:

locale -a

If your local locale is not among those listed, install it. To do this, just edit the file /etc/locale.gen by removing the comments before the line(s) with the desired locale, and then run the command:

sudo locale-gen

If you need to change the default locale, do:

sudo dpkg-reconfigure locales

To change the time zone, follow the steps below:

sudo timedatectl set-timezone Europe/Kyiv

You can now proceed to install PostgreSQL:

sudo apt install -y postgresql-14 postgresql-14-postgis-3

Setting

Create a user (role) and database for ERP USERSIDE. The example below creates a user named userside and a database with the same name. The PostGis extension is then connected to the database, required to manipulate geometric data. After the first line has been executed, you will need to enter the password for the new user twice - make a note of this password, you will need it later to install ERP USERSIDE

sudo -u postgres createuser userside -P
sudo -u postgres createdb -e -E "UTF-8" -l "uk_UA.UTF-8" -O userside -T template0 userside
sudo -u postgres psql -d userside -c "CREATE EXTENSION postgis"

If your PostgreSQL is installed on another server, you will need to make adjustments to the postgresql.conf and pg_hba.conf files located in /etc/postgresql/14/main/. In postgresql.conf you need to uncomment and change the value of listen_addresses parameter, specifying there all IP addresses of server interfaces where it can accept connections to PostgreSQL. In the pg_hba.conf file, add a line at the very end, similar to the previous ones, indicating from which address the user of ERP USERSIDE can connect. But if your PostgreSQL is on the same server as PHP and everything else, there is no need to make any adjustments to this file.

PostgreSQL server fine-tuning

Refer to Fine tuning.

Redis

Alternative installation method

The standard Debian 10 repository includes version 5.0.3 of Redis, released in December 2018. This version is suitable for ERP USERSIDE operation. If you want to install the latest version from branch 6, you will have to build Redis manually. If you have no experience with this, simply install Redis as shown below - that's quite enough. If you are using an Ubuntu server, you can use the official PPA-repository.

For information on manually building Redis and on the PPA repository, see official Redis website.

Installation

sudo apt install -y redis-server

Setting

By default Redis accepts connections without a password, but we strongly recommend setting a password. Since the password is transmitted openly (Redis does not provide encryption as it focuses on query speed and extra steps like encryption do not apply), you need to create a really long and complex password. This can be done, for example, using the sha256sum utility as follows:

echo "some unique long phrase" | sha256sum

The output will be a sha256 hash, which you will use as your real password. Next, instead of MYPASSWORDHERE, use this particular password. Make a note of it.

Specify this password in the Redis configuration file:

sudo sed -i 's@^.*requirepass .*@requirepass MYPASSWORDHERE@g' /etc/redis/redis.conf

where MYPASSWORDHERE is your Redis password.

Timeout must also be disabled (on some versions of Redis it is enabled):

sudo sed -i 's@^timeout .*@timeout 0@' /etc/redis/redis.conf

Restart Redis and make sure, that it works (should get PONG in response):

sudo systemctl restart redis
redis-cli -h 127.0.0.1 -p 6379 -a MYPASSWORDHERE ping

RabbitMQ

Only required for version 3.16 and newer.

The standard Debian 10 repository includes an older, no longer supported version of RabbitMQ 3.7. Adding alternative repositories is therefore a must in this case. The official RabbitMQ website contains fairly detailed information on installing RabbitMQ for each operating system.

Installation

sudo apt-key adv --keyserver "hkps://keys.openpgp.org" --recv-keys "0x0A9AF2115F4687BD29803A206B73A36E6026DFCA"
curl -1sLf https://dl.cloudsmith.io/public/rabbitmq/rabbitmq-erlang/gpg.E495BB49CC4BBE5B.key | sudo apt-key add -
curl -1sLf https://dl.cloudsmith.io/public/rabbitmq/rabbitmq-server/gpg.9F4587F226208342.key | sudo apt-key add -

Copy and paste the following block into the command line in its entirety

sudo tee /etc/apt/sources.list.d/rabbitmq.list << EOF
deb https://dl.cloudsmith.io/public/rabbitmq/rabbitmq-erlang/deb/ubuntu bionic main
deb-src https://dl.cloudsmith.io/public/rabbitmq/rabbitmq-erlang/deb/ubuntu bionic main
deb https://dl.cloudsmith.io/public/rabbitmq/rabbitmq-server/deb/ubuntu bionic main
deb-src https://dl.cloudsmith.io/public/rabbitmq/rabbitmq-server/deb/ubuntu bionic main
EOF

sudo apt update -y

sudo apt install -y erlang-base \
    erlang-asn1 erlang-crypto erlang-eldap erlang-ftp erlang-inets \
    erlang-mnesia erlang-os-mon erlang-parsetools erlang-public-key \
    erlang-runtime-tools erlang-snmp erlang-ssl \
    erlang-syntax-tools erlang-tftp erlang-tools erlang-xmerl \
    libncurses5

sudo apt install rabbitmq-server -y --fix-missing

Installing the necessary add-ons

sudo rabbitmq-plugins enable rabbitmq_management --offline
sudo rabbitmq-plugins enable rabbitmq_web_stomp --offline

Setting

Copy and paste the following block in its entirety:

sudo tee /etc/rabbitmq/rabbitmq.conf << EOF
listeners.tcp.default = 5672

web_stomp.port = 15674
web_stomp.cowboy_opts.max_keepalive = 60
EOF

Now you need to create users. We recommend using three different accounts: for server administration (full rights), for userside and modules (full rights but no administrative rights) and web-stomp user for websocket (minimum rights to read certain broker objects).

Create a user to administer RabbitMQ. This example uses the user name admin and the password password. The user is tagged immediately after creation administrator, giving the user maximum administrator rights and then setting permissions for vhost / allowing full configuration, write and read access to everything within this vhost*.

sudo rabbitmqctl add_user "admin" "password"
sudo rabbitmqctl set_user_tags "admin" "administrator"
sudo rabbitmqctl set_permissions -p "/" "admin" ".*" ".*" ".*"

Create a user on whose behalf ERP USERSIDE and modules will operate. Example for user name userside (you do not need to give admin rights to this user):

sudo rabbitmqctl add_user "userside" "password2"
sudo rabbitmqctl set_permissions -p "/" "userside" ".*" ".*" ".*"

Create a user for the WebSTOMP module. You will need it to use WebSocket notifications (from version 3.17 onwards). Instead of websock-user you can specify another user name, but we recommend leaving this. The websock-password can be replaced by a password, but this password will be passed to the browser in clear text, so there is no point in making it too complex:

sudo rabbitmqctl add_user "websock-user" "websock-password"
sudo rabbitmqctl set_permissions -p "/" "websock-user" "^userside-stomp:id-.*" "" "^userside-stomp:id-.*"

* vhost - is a virtual host within RabbitMQ, allowing different uses of the same server by different applications. Such as different databases on the same RDBMS server. vhost has a default name of / and this is almost always enough for you. But if you plan to run multiple copies of ERP USERSIDE on the same server, for example, you will need to create a different vhost for each copy and therefore users for it. Refer to official manual for details.

Management

One of the commands above installs a management module in RabbitMQ, providing a convenient WEB interface for monitoring, diagnosing and managing the RabbitMQ server. This module can be used to monitor the server, the number of queued messages and other statuses. All this can also be done using a console utilityrabbitmqctl, but the use of a WEB interface can be much more intuitive and user-friendly. If you don't need a WEB interface to manage the server, you can skip installing the rabbitmq_management module during the installation phase.

By default, the WEB management interface is available at http://userside.mycompany.com:15672

You can read more about the control module on the official RabbitMQ website.

PHP

Alternative repository

If your operating system has the required version of PHP in its standard package repository, you can install PHP and extensions directly from the main operating system repository. For example, the Debian-11 (Bullseye) version contains PHP version 7.4 in its standard repository, which is suitable for ERP USERSIDE 3.16 and 3.17.

However, if the version of your operating system is older, the correct versions of the packages may simply not be there. If this is the case, you can add an alternative repository to your operating system. Execute the commands below to add an alternative repository to the system:

sudo wget -O /etc/apt/trusted.gpg.d/php.gpg https://packages.sury.org/php/apt.gpg
echo "deb https://packages.sury.org/php/ $(lsb_release -sc) main" | sudo tee /etc/apt/sources.list.d/php.list
sudo apt update

Installation

Execute the following commands:

sudo apt install -y php7.4-{fpm,cli,common,curl,intl,json,mbstring,opcache,pgsql,readline,xml,zip,snmp,gd}

If you plan to use LDAP, the php-ldap extension must be installed:

sudo apt install -y php7.4-ldap

If you plan to use TurboSMS to send SMS, you will also need the php-soap extension:

sudo apt install -y php7.4-soap

Setting

The following are commands that make changes to the configuration files.

sudo sed -i "s@^;date.timezone.*@date.timezone = $(cat /etc/timezone)@" /etc/php/7.4/fpm/php.ini
sudo sed -i "s@^;date.timezone.*@date.timezone = $(cat /etc/timezone)@" /etc/php/7.4/cli/php.ini
sudo sed -i "s@;cgi.fix_pathinfo=1@cgi.fix_pathinfo=0@" /etc/php/7.4/fpm/php.ini
sudo sed -i "s@post_max_size = 8M@post_max_size = 50M@" /etc/php/7.4/fpm/php.ini
sudo sed -i "s@upload_max_filesize = 2M@upload_max_filesize = 50M@" /etc/php/7.4/fpm/php.ini
sudo sed -i "s@max_execution_time.*@max_execution_time = 120@" /etc/php/7.4/fpm/php.ini
sudo sed -i "s@max_input_time.*@max_input_time = 120@" /etc/php/7.4/fpm/php.ini
sudo sed -i 's@;request_terminate_timeout.*@request_terminate_timeout = 120@' /etc/php/7.4/fpm/pool.d/www.conf

sudo systemctl restart php7.4-fpm

Fine-tuning

By default there are 4 processes running in the PHP-FPM pool, to ensure that it can run on any, even the weakest, server. This means that only 4 requests can be processed at a time, the rest will wait in the queue. The PHP-FPM pool needs to be optimised so that the number of running processes covers system usage, and there are enough redundant processes that can be started automatically by the process manager.

The entire tuning process is described in Fine tuning.

NGINX

Alternative official repository

The version of NGINX supplied in the Debian repository is suitable for use and there is no need to add an alternative repository. However, if you want to always have the latest version, run the following lines to add the official nginx repository to your operating system:

wget --quiet -O - http://nginx.org/keys/nginx_signing.key | sudo apt-key add -
echo "deb http://nginx.org/packages/mainline/debian/ $(lsb_release -sc) nginx" | sudo tee -a /etc/apt/sources.list.d/nginx.list
echo "deb-src http://nginx.org/packages/mainline/debian/ $(lsb_release -sc) nginx" | sudo tee -a /etc/apt/sources.list.d/nginx.list

If you have a different operating system, you can find the necessary commands for it on the official NGINX website: https://docs.nginx.com/nginx/admin-guide/installing-nginx/installing-nginx-open-source/

Installation

sudo apt-get remove -y nginx-common apache2
sudo apt-get update
sudo apt-get install -y nginx

Setting

NGINX should run as the www-data user - the www-pool of php-fpm runs as the same user:

sudo sed -i "s@^user.*;@user www-data www-data;@" "/etc/nginx/nginx.conf"

The following configuration example assumes that ERP USERSIDE will be installed in the standard system directory /var/www/userside. If you wish to install ERP USERSIDE in a different directory, please remember to correct it in all subsequent examples. To make sure you get it right, we recommend using the catalogue /var/www/userside.

This directory will contain the web-root, i.e. the files accessible via the http protocol.

Now edit the file /etc/nginx/conf.d/default.conf. Or delete it and create a new file with an arbitrary name, e.g. /etc/nginx/conf.d/userside.conf. In either case, regardless of your choice, the contents of the file should be as follows (specify your domain name instead of userside.mycompany.com):

server {
    listen       80;
    server_name  userside.mycompany.com;
    charset      utf-8;
    client_max_body_size 50M;

    access_log  /var/log/nginx/userside-access.log;
    error_log   /var/log/nginx/userside-error.log;

    root   /var/www/userside/userside3;
    index  index.php;

    location = /favicon.ico { access_log off; log_not_found off; }
    location = /robots.txt  { access_log off; log_not_found off; }

    location / {
        try_files $uri $uri/ =404;
    }

    location ~* ^.+\.(css|js|ogg|ogv|svg|svgz|eot|otf|woff|mp4|ttf|rss|atom|jpg|jpeg|gif|png|ico|zip|tgz|gz|rar|bz2|doc|xls|exe|ppt|tar|mid|midi|wav|bmp|rtf)$ {
        access_log    off;
        log_not_found off;
        expires       max;
        add_header    Pragma public;
        add_header    Cache-Control "public";
    }

    location ~ \.php$ {
        try_files     $uri =404;
        fastcgi_split_path_info ^(.+\.php)(/.+)$;
        fastcgi_pass  unix:/run/php/php7.4-fpm.sock;
        fastcgi_index index.php;
        fastcgi_param SCRIPT_FILENAME $document_root$fastcgi_script_name;
        fastcgi_read_timeout 600;
        include       fastcgi_params;
    }

    location /ws {
        proxy_pass http://127.0.0.1:15674/ws;
        proxy_http_version 1.1;
        proxy_set_header Upgrade $http_upgrade;
        proxy_set_header Connection "Upgrade";
        proxy_set_header Host $host;
    }

    location ~ /\.ht { deny  all; }

    error_page 404 /404.php?type=404;
    error_page 403 /404.php?type=403;
    error_page 500 /404.php?type=500;

    location = /404.php {
        root /var/www/userside/userside3/main/error/;
        internal;
    }
}

You may also want to configure SSL and anything else. This topic is beyond the scope of this manual.

If you installed RabbitMQ 'on a different server, or changed the WebSTOMP port value from 15674 to some other server, specify the IP address of the server with RabbitMQ and the port number on the line proxy_pass http://127.0.0.1:15674/ws;. The protocol must remain http. The path must remain /ws.

Check the configuration and if it is OK, reboot nginx:

sudo nginx -t && sudo systemctl restart nginx