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.

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 full-upgrade -y
sudo apt install -y gnupg debian-keyring 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 in the clear (Redis does not provide encryption, as it focuses on speed of request processing and unnecessary steps like encryption do not apply), you need to create a really long and complex password. This can be done, for example, using openssl as follows:

openssl rand --hex 32

The output will be a random set of 32 bytes in 16-character form, which you will use as a password. Next, you will need to replace the word MYPASSWORDHERE with this generated string. Make a note of it. Then in the settings you will specify this string 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 11 repository includes an older version of RabbitMQ 3.8. You can use it - it is supported. However, this version is relatively old and your best option is to install a new version from alternative repositories. The official RabbitMQ website has fairly detailed information on installing RabbitMQ for each operating system.

If you use Debian 12, notice that you still need to specify bullseye in the sources.list (below), as bookworm (or as stated on the rabbitmq website - bookwork) doesn't work! This is probably a temporary problem related to the Debian 12 Bookworm repository.

Adding alternative repositories

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

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://ppa1.novemberain.com/gpg.E495BB49CC4BBE5B.key | sudo gpg --dearmor | sudo tee /usr/share/keyrings/rabbitmq.E495BB49CC4BBE5B.gpg > /dev/null
curl -1sLf https://ppa1.novemberain.com/gpg.9F4587F226208342.key | sudo gpg --dearmor | sudo tee /usr/share/keyrings/rabbitmq.9F4587F226208342.gpg > /dev/null

sudo tee /etc/apt/sources.list.d/rabbitmq.list <<EOF
deb [signed-by=/usr/share/keyrings/rabbitmq.E495BB49CC4BBE5B.gpg] https://ppa1.novemberain.com/rabbitmq/rabbitmq-erlang/deb/debian bullseye main
deb-src [signed-by=/usr/share/keyrings/rabbitmq.E495BB49CC4BBE5B.gpg] https://ppa1.novemberain.com/rabbitmq/rabbitmq-erlang/deb/debian bullseye main
deb [signed-by=/usr/share/keyrings/rabbitmq.9F4587F226208342.gpg] https://ppa1.novemberain.com/rabbitmq/rabbitmq-server/deb/debian bullseye main
deb-src [signed-by=/usr/share/keyrings/rabbitmq.9F4587F226208342.gpg] https://ppa1.novemberain.com/rabbitmq/rabbitmq-server/deb/debian bullseye main
EOF

sudo apt update
 
sudo apt-get 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

Installation

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_user_tags "userside" "monitoring"
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.

Restart the rabbitmq service:

sudo systemctl restart rabbitmq-server

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.

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 php8.1-{fpm,cli,common,curl,intl,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 php8.1-ldap

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

sudo apt install -y php8.1-soap

Setting

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

Please note that if your time zone Europe/Kiev, then instead of $(cat /etc/timezone) You should write Europe/Kyiv. Debian 11 has not yet made changes to rename the time zone, whereas PHP 8.1 already does.

sudo sed -i "s@^;date.timezone.*@date.timezone = $(cat /etc/timezone)@" /etc/php/8.1/fpm/php.ini
sudo sed -i "s@^;date.timezone.*@date.timezone = $(cat /etc/timezone)@" /etc/php/8.1/cli/php.ini
sudo sed -i "s@;cgi.fix_pathinfo=1@cgi.fix_pathinfo=0@" /etc/php/8.1/fpm/php.ini
sudo sed -i "s@post_max_size = 8M@post_max_size = 100M@" /etc/php/8.1/fpm/php.ini
sudo sed -i "s@upload_max_filesize = 2M@upload_max_filesize = 100M@" /etc/php/8.1/fpm/php.ini
sudo sed -i "s@max_execution_time.*@max_execution_time = 300@" /etc/php/8.1/fpm/php.ini
sudo sed -i "s@max_input_time.*@max_input_time = 300@" /etc/php/8.1/fpm/php.ini
 
sudo systemctl restart php8.1-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 provided in the Debian repository is fully usable 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
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
sudo apt update

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 remove -y nginx-common apache2
sudo apt 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"
sudo systemctl restart nginx

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 default_server;
    server_name  userside.mycompany.com;
    charset      utf-8;
    client_max_body_size 100M;

    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/php8.1-fpm.sock;
        fastcgi_index index.php;
        fastcgi_param SCRIPT_FILENAME $document_root$fastcgi_script_name;
        fastcgi_read_timeout 300;
        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, but if you are running a version lower than 3.8 on your host you should definitely install at least 3.8.

Installing the necessary packages

sudo apt install -y python3-dev python3-pip python3-venv libffi-dev
sudo pip install --upgrade pip wheel setuptools

Supervisor

Only required for version 3.16 and newer.

Installation

sudo apt install -y supervisor

Downloading and running the installer

Set up after installation

Configuration of system services

After installation, copy the sample system services configuration files and customise them if necessary (for example, specify the path to the userside directory if it is different from /var/www/userside). Run the commands:

sudo cp etc/us-core-worker.conf-example /etc/supervisor/conf.d/us-core-worker.conf
sudo cp microservice/poller/etc/usm_poller.conf-example /etc/supervisor/conf.d/usm_poller.conf
sudo cp etc/logrotate-example /etc/logrotate.d/userside
sudo cp microservice/poller/etc/logrotate-example /etc/logrotate.d/usm_poller
sudo cp etc/crontab-example /etc/cron.d/userside

Install the necessary dependencies for usm_poller

cd microservice/poller
sudo -H python3 -m venv venv
sudo -H ./venv/bin/pip install -U pip wheel setuptools
sudo -H ./venv/bin/pip install -U -r requirements.txt

Launching the supervisor

The supervisor monitors the health of the services specified in its configuration. To start the supervisor, execute:

sudo systemctl restart supervisor

After launching the supervisor, after a few seconds you can observe the state of all the services it monitors. All services must be in the RUNNING state:

sudo supervisorctl status

Immediately after installation

This completes the ERP USERSIDE installation. Now perform the following steps:

Open the system page http://userside.mydomain.com/oper/ and log in (default username: Admin, password: 1234).
Configure Websocket setting at: Settings - Main - WebSocket. Enable and enter the user name and password of the WebStomp user you created earlier under RabbitMQ.
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

We strongly recommend performing test updates on a copy of the system.

To perform an upgrade, run the installer in install mode and follow the instructions:

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

After updating the USERSIDE, you must be sure to update the usm_poller dependencies:

sudo -H microservice/poller/venv/bin/pip install -U -r microservice/poller/requirements.txt

Now you need to restart all the services that are supervised by the supervisor and make sure that all of them are started and in the RUNNING state:

sudo supervisorctl restart all
sudo supervisorctl status

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 run cache/flush-all

For version 3.17 and below, instead of the last command:

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.