Installation for version 3.18

ATTENTION: These instructions are valid for ERP USERSIDE versions 3.18

Description

For the sake of simplicity, commands for the Linux Debian 11 (Bullseye) 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 https://github.com/userside/userside-docker.

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.18 (current stable)

PHP: 8.1
PHP extensions: ctype, gd, json, libxml, mbstring, openssl, pdo, pdo_pgsql, posix, simplexml, snmp, sockets, zlib, pcntl
PHP Extensions: ldap, soap
Python: 3.8+
Python Modules: pip, venv
PostgreSQL: 10+
Redis: 5+
RabbitMQ: 3.8+
Supervisor

3.16, 3.17

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 gnupg debian-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
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:

sudo sh -c 'echo "deb http://apt.postgresql.org/pub/repos/apt $(lsb_release -cs)-pgdg main" > /etc/apt/sources.list.d/pgdg.list'
wget --quiet -O - https://www.postgresql.org/media/keys/ACCC4CF8.asc | sudo apt-key add -
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/Kiev

You can now proceed to install PostgreSQL:

sudo apt install -y postgresql-15 postgresql-15-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/15/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 11 repository includes a version of Redis 6.0.16. This version is suitable for ERP USERSIDE. If you want to install the latest version you will have to build Redis manually. If you have no experience with this, just install Redis as shown below - that's fine. 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. Then, instead of MYPASSWORDHERE, you will need to substitute this particular hash. Make a note of it. Then in the settings you will specify this hash as the Redis password.

Specify the resulting passphrase hash in the Redis configuration file:

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

where MYPASSWORDHERE should be replaced with the passphrase hash received earlier.

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

curl -1sLf "https://keys.openpgp.org/vks/v1/by-fingerprint/0A9AF2115F4687BD29803A206B73A36E6026DFCA" | sudo gpg --dearmor | sudo tee /usr/share/keyrings/com.rabbitmq.team.gpg > /dev/null
curl -1sLf https://dl.cloudsmith.io/public/rabbitmq/rabbitmq-erlang/gpg.E495BB49CC4BBE5B.key | sudo gpg --dearmor | sudo tee /usr/share/keyrings/io.cloudsmith.rabbitmq.E495BB49CC4BBE5B.gpg > /dev/null
curl -1sLf https://dl.cloudsmith.io/public/rabbitmq/rabbitmq-server/gpg.9F4587F226208342.key | sudo gpg --dearmor | sudo tee /usr/share/keyrings/io.cloudsmith.rabbitmq.9F4587F226208342.gpg > /dev/null

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

sudo tee /etc/apt/sources.list.d/rabbitmq.list << EOF
deb [signed-by=/usr/share/keyrings/io.cloudsmith.rabbitmq.E495BB49CC4BBE5B.gpg] https://dl.cloudsmith.io/public/rabbitmq/rabbitmq-erlang/deb/ubuntu bionic main
deb-src [signed-by=/usr/share/keyrings/io.cloudsmith.rabbitmq.E495BB49CC4BBE5B.gpg] https://dl.cloudsmith.io/public/rabbitmq/rabbitmq-erlang/deb/ubuntu bionic main
deb [signed-by=/usr/share/keyrings/io.cloudsmith.rabbitmq.9F4587F226208342.gpg] https://dl.cloudsmith.io/public/rabbitmq/rabbitmq-server/deb/ubuntu bionic main
deb-src [signed-by=/usr/share/keyrings/io.cloudsmith.rabbitmq.9F4587F226208342.gpg] 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

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 curl -sSLo /usr/share/keyrings/deb.sury.org-php.gpg https://packages.sury.org/php/apt.gpg
sudo sh -c 'echo "deb [signed-by=/usr/share/keyrings/deb.sury.org-php.gpg] https://packages.sury.org/php/ $(lsb_release -sc) main" > /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:

curl https://nginx.org/keys/nginx_signing.key | gpg --dearmor \
    | sudo tee /usr/share/keyrings/nginx-archive-keyring.gpg >/dev/null
gpg --dry-run --quiet --no-keyring --import --import-options import-show /usr/share/keyrings/nginx-archive-keyring.gpg
echo "deb [signed-by=/usr/share/keyrings/nginx-archive-keyring.gpg] \
http://nginx.org/packages/debian `lsb_release -cs` nginx" \
    | sudo tee /etc/apt/sources.list.d/nginx.list
echo -e "Package: *\nPin: origin nginx.org\nPin: release o=nginx\nPin-Priority: 900\n" \
    | sudo tee /etc/apt/preferences.d/99nginx

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

Python

Debian 11 contains Python 3.9 in the standard repository - this is sufficient, so no alternate repositories are needed.

Installation

sudo apt install -y python3 python3-dev python3-pip
sudo -H python3 -m pip install --upgrade pip virtualenv

Supervisor

Only required for version 3.16 and newer.

Installation

sudo apt install -y supervisor

Downloading and running the installer

Set up after installation

Scheduler

Copy and paste the following lines into the command line to add the scheduler to the system CRON:

sudo tee /etc/cron.d/userside << EOL
* * * * *   www-data   /usr/bin/php /var/www/userside/userside cron > /dev/null
EOL

Background core processes

Only required for version 3.16 and newer.

The kernel background process is in constant waiting for messages from the RabbitMQ broker. These messages are used to transmit tasks or the results of the work of other workers.

The automatic start-up and monitoring of kernel workers must be set up. Supervisor is used for this purpose. Create a configuration to start the supervisor service by copying the following block in its entirety and pasting it into the command line:

sudo tee /etc/supervisor/conf.d/us-core-worker.conf << EOL
[program:us-core-worker]
process_name=%(program_name)s_%(process_num)02d
command=/usr/bin/php /var/www/userside/userside queue/listen
autostart=true
autorestart=true
user=www-data
numprocs=10
redirect_stderr=true
stdout_logfile=/var/www/userside/var/log/core-worker.log
EOL

The supervisor now needs to be restarted:

sudo systemctl restart supervisor

The supervisor is controlled by the supervisorctl utility. For example, to output a list of all processes running and controlled by the supervisor, you can run the command:

sudo supervisorctl status

To restart the kernel workers (us-core-worker), you can run the command:

sudo supervisorctl restart us-core-worker:*

Background Poller microservice processes

Only required for version 3.16 and newer.

The pollear microservice - is a background process that executes commands to interact with the equipment. The microservice files are supplied with ERP USERSIDE and are located in /var/www/userside/microservice/poller.

Installation

Poller is implemented in the Python programming language and requires additional modules for its operation. The best way to do this is to use a Python virtual environment. In this case, all extensions will be installed in a local subdirectory, avoiding any conflicts in the system and allowing for more convenient and easier handling of these extensions in the future (version upgrades, etc.).

Execute the following commands to set up the virtual environment:

cd /var/www/userside/microservice/poller
sudo -H python3 -m virtualenv -p /usr/bin/python3 venv
sudo -H ./venv/bin/pip install --upgrade -r requirements.txt

Setting

As part of the poller an example supervisor settings file is supplied. Copy it as a work file.

sudo cp etc/us-poller-microservice.conf-example /etc/supervisor/conf.d/us-poller-microservice.conf

Restart the supervisor

sudo systemctl restart supervisor

Check that everything has started correctly

sudo supervisorctl status

If there are problems with the start-up, try running the poller microservice manually and analyse the output

sudo /var/www/userside/microservice/poller/venv/bin/python3 /var/www/userside/microservice/poller/worker.py

Immediately after installation

This completes the ERP USERSIDE installation. You can now perform the following steps:

Open the system page http://userside.mydomain.com/oper/ and log in (default username: Admin, password: 1234).
Make the basic settings in: Settings - Main.
Set up an interaction with billing according to instructions.
Read the instructions on the page Where to start?.
It is advisable to restrict access to the API file '/var/www/userside/userside3/api.php' from certain IP addresses.

System upgrade

Technically any end-to-end upgrade is possible, from ERP USERSIDE 3.11 to the latest version. However, there are situations where data migration problems arise with this upgrade. This is most likely to occur on older systems where data has been accumulated over many years (starting with the upgrade to ERP USERSIDE version 3). This is why we recommend that you upgrade your system in stages. If you have 3.11, first upgrade to the latest 3.12, then 3.13 etc. Note that each version has different system requirements (see above), but most are not restricted to the version above. That is, if you have 3.11 and want to upgrade to 3.16, you can install the latest version of PostgreSQL, Redis, RabbitMQ, etc. immediately, even though you will be doing a staged upgrade. The only thing to consider is the PHP versions. Different versions of ERP USERSIDE support a different range of PHP versions. Unfortunately, this cannot be avoided. For example, we have not tested ERP USERSIDE 3.14 with PHP 7.4 because it simply did not exist at that time. Therefore we simply cannot guarantee that it will work on this version. But the range of supported versions of PHP is quite wide, so you don't have to install a new version of PHP for every version of ERP USERSIDE. For example, to upgrade from 3.11 to 3.16 you only need a few steps:

upgrade PHP to version 7.1 and on this version you can upgrade to as much as 3.15. Also install all necessary dependencies at once for version 3.16.
After upgrading to 3.15, upgrade to PHP 7.4 and upgrade to 3.16.

We recommend that you make a copy of your system in order to carry out the upgrade safely. Refer to HOWTO: Cloning USERSIDE. You can always delete a copy and start over. It's easy and safe. But if you want to upgrade a running system, do it at the lowest load times, with time to spare for disaster recovery in case something goes wrong. Always make sure to back up the database and files before upgrading. If an upgrade is interrupted, especially during the data migration phase, there is a risk that it will be very difficult or even impossible to restore the data correctly. In general, the responsibility for having an up-to-date backup is entirely yours.

You may need to upgrade PostgreSQL before upgrading. Refer to our PostgreSQL upgrade instructions for this procedure before you start the ERP USERSIDE upgrade process.

Upgrade process

After making a copy of the system, or at least a full backup of the working system if you do not want to make a clone, you only need to run the installation command:

cd /var/www/userside-new
sudo -u www-data php userside_install.phar install

Next, interactively select the version to upgrade, specify the missing configuration parameters for the new version, if any, and wait for the upgrade to complete. After upgrading, be sure to check at least the basic functionality of the system. This is especially true for a staged upgrade: do not upgrade to the next stage if the current stage has ended with an error or the system has stopped working correctly.

For version 3.16 and newer.

Poller's microservice dependencies may change after the upgrade. Run this command every time after an upgrade, even if more often than not it does nothing:

cd /var/www/userside/microservice/poller
sudo -H ./venv/bin/pip install --upgrade -r requirements.txt

After upgrading, it is imperative that the background processes managed by the supervisor are restarted so that the upgraded files start working:

sudo systemctl restart supervisor

System maintenance

A few simple steps are recommended to maintain the system and ensure reliable operation in the future:

make a periodic backup of the database
back up downloaded files periodically (this can be done simply by archiving the /var/www/userside/var/attachments directory and .env file)
periodically monitor server performance (using htop, atop) and the RabbitMQ broker and make decisions about scaling fpm pools, kernel background processes and microservices

Backup

Set up periodic backups of the database and user files. Preferably at least once a day at times of least server load. In PostgreSQL there are two ways to back up the database: dump and sql-script. Each has its own advantages and disadvantages. The first creates a secure dump of the entire database, while the second creates an SQL script that can be run to recover both the structure and the data. We recommend referring to documentation on using the pg_dump command to select a method or parameter set that is more suitable for you.

Below are two commands to back up the database - choose one and add it to your crontab:

# DUMP
sudo -u postgres pg_dump --no-acl -Fc userside > /backup/userside.dump

# SQL-script
sudo -u postgres pg_dump --no-acl -Fp -Z 5 userside > /backup/userside.sql.gz

You can use the following command (for version 3.15 and later) to create a minimal backup of the files:

sudo tar -czf /backup/userside.tgz .env common/config/settings.json var/attachments

These files, together with the database, will be sufficient to restore USERSIDE operation. But you can back up the entire /var/www/userside directory for the sake of safety.

Restore from backup

The pg_restore command is used to restore from dump. Documentation on using pg_restore. The psql utility is used to recover from an SQL script. Documentation on using psql.

DUMP

The dump contains the entire database with all its elements. Therefore, the database must not exist on the server before restoring it from the dump - delete the database before restoring from the dump. It is also important that a database user (the owner of all items) already exists - create one before you restore, if you are restoring the database on a new server where the required user does not yet exist.

Also note that the dump structure may not be compatible between different versions of PostgreSQL. It's not necessarily true, but it's quite likely.

Use the command to recover from the dump:

sudo -u postgres pg_restore --clean --if-exists --create --exit-on-error --dbname=postgres /backup/userside.dump

Note that the name of the database in the command must be postgres, as the name of the database to be restored is taken from the dump.

SQL-script

You can restore the database from an SQL-script by using the command:

gunzip < /backup/userside.sql.gz | sudo -u postgres psql -d userside

The database must already exist before this command is executed, but it must be empty. There must also be a user (owner) of the database objects.

After database restoring

After restoring the database by any means, the ERP USERSIDE cache must be cleared, as the cache now contains data other than the data in the database. Go to /var/www/userside and run the clear cache command:

cd /var/www/userside
php userside cache/flush-all

If the versions of the USERSIDE files and the database dump are different, the USERSIDE version must be adjusted to match the data after restoring the database from the backup. To do this, in the /var/www/userside directory, run the command:

sudo -u www-data php userside_install.phar repair

PostgreSQL maintenance

The PostgreSQL architecture is such that operations that change data in tables always create a new copy of that data and mark the old data as "dead" - this greatly speeds up these operations, but database files can grow in size over time, which can also have a significant impact on performance.

By default, Postgres has an automatic vacuuming system enabled that runs continuously in parallel with the RDBMS itself. Automatic vacuumisation removes "dead" tuples from the files so that the freed space can be reused by new data. But this vacuum mode does not "defragment" the files, leaving them at least the same size.

In most cases automatic vacuuming is sufficient and we recommend that you do not disable autovacuuming so that your files do not grow to enormous sizes and your database does not slow down by tens or hundreds of times.

The full vacuuming procedure, which can be run manually, defragments the database by reducing the size of the database files. But it is executed with full table locking! The full vacuuming procedure (as well as rebuilding the indexes) should preferably be performed during the lowest load on the server when clearly needed (if the database file volume is too large, tens or hundreds of times the normal volume). The database tables will be locked during this procedure, as this procedure creates new data files and only transfers 'live' data to them. After this procedure, it is also advisable to perform an index rebuilding procedure. For more information on vacuuming and re-indexing, see the PostgreSQL documentation.

The following commands are aliases of the SQL queries of the same name. If you find it easier to run SQL queries instead of commands, refer to the documentation in the links above.

sudo -u postgres vacuumdb --full --analyze userside
sudo -u postgres reindexdb userside

If you have started the vacuuming procedure manually before, you must have used the parameter -j or --jobs to specify the number of threads. When using full vacuuming, it is undesirable to use multi-threading to avoid interlocking of tables.

RabbitMQ monitoring

Only required for version 3.16 and newer.

The RabbitMQ management system graphs the message queue load in a clear way. A consistently high or potentially increasing number of queued messages indicates the need for more background processes. For example, if the userside queue has a consistently high number of messages (more than 10...20), it is worth adding another instance of the us-core-worker handler. To do this, edit the supervisor file /etc/supervisor/conf.d/us-core-worker.conf to increase the value of numprocs and then restart the supervisor.