Installation for version 3.18

ATTENTION: These instructions are valid for ERP USERSIDE versions 3.18 (3.19)

Description

For the sake of simplicity, the commands for the Linux Debian 12 (bookworm) 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 administering operating systems, we recommend you to use Debian or Ubuntu Server LTS. Because of their simplicity and because our technical support is much more familiar with Debian-like distributions. The likelihood of being able to tell you something not related to ERP USERSIDE, but related to operating system administration, will be much higher 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, you may find it more convenient to use a ready-made environment based on Docker images, which we have prepared specially, including everything you need to run ERP USERSIDE. In this case, you will not have to configure anything, except to perform simple Docker-bundle settings https://github.com/userside/userside-docker.

Requirements

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

Also note that your operating system must be configured with the correct time zone and locale. The correct display of information and correct sorting depends on this.

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

3.19 (beta)

PHP: 8.3
PHP extensions: ctype, gd, json, libxml, mbstring, openssl, pdo, pdo_pgsql, posix, simplexml, snmp, sockets, zlib, pcntl
Additional PHP extensions: ldap, soap
Python: 3.9+ (preferably 3.11)
Python modules: pip, venv
PostgreSQL: 12+ (preferably 16)
Redis: 5+ (preferably 7)
RabbitMQ: 3.10+ (preferably 3.13)
Supervisor

3.18 (current stable)

PHP: 8.1
PHP extensions: ctype, gd, json, libxml, mbstring, openssl, pdo, pdo_pgsql, posix, simplexml, snmp, sockets, zlib, pcntl
Additional PHP extensions: ldap, soap
Python: 3.8+ (preferably 3.11)
Python modules: pip, venv
PostgreSQL: 10+ (preferably 16)
Redis: 5+ (preferably 7)
RabbitMQ: 3.8+ (preferably 3.13)
Supervisor

Main Agreements

The directory where ERP USERSIDE is installed is /var/www/userside. Inside this directory there should be a subdirectory userside3, which is the root directory for the WEB server. If you want to use a different directory for ERP USERSIDE, remember to make the appropriate corrections to all the examples in these instructions.

Create the directory:

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

You will need to allocate a domain name for ERP USERSIDE. The examples below use userside.mycompany.com, but you will need to change it to your own. Write this domain name in /etc/hosts if it is different from the hostname of the installation.

Installing the required components

The installation will be shown for the currently stable version of ERP USERSIDE 3.18. If you are going to install 3.19-beta, you will need to install PHP-8.3 instead of 8.1, and note the difference in nginx configuration. Otherwise, the steps are identical.

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

Copy and paste the following lines in their entirety:

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

sudo apt update
sudo apt full-upgrade -y
sudo apt install -y gnupg ca-certificates lsb-release debian-archive-keyring debian-keyring libsnmp-dev snmp-mibs-downloader

PostgreSQL

Alternative official repository

We strongly recommend using the latest version of PostgreSQL, as this always has a positive impact on speed. Add the official Postgres repository to the system:

sudo sh -c 'echo "deb https://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.

Installation

Caution! Before installing PostgreSQL, your operating system must have your local locale and correct time zone set! This can be done later, but it will be much easier if it is done before installing PostgreSQL. Run the following command to make sure the correct locale is present:

locale -a

If your local locale is not among those listed, then install it. To do this, simply edit the /etc/locale.gen file 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, then execute:

sudo dpkg-reconfigure locales

To change the time zone, execute:

sudo timedatectl set-timezone Europe/Kyiv

Now you can move on to the PostgreSQL installation:

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

Setting

Create a user and database for ERP USERSIDE. The example below creates a user named userside and a database with the same name. If your locale is not uk_UA, remember to change the command. The PostGis extension needed to work with geographic data is then connected to the database. After doing the first line, you will need to enter the password for the new user twice - make a note of this password, you will need it later to set up the 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 corrections to the files postgresql.conf and pg_hba.conf located in the /etc/postgresql/16/main/ directory. In the postgresql.conf file, you must uncomment and change the value of the listen_addresses parameter, specifying there all IP addresses of the server interfaces on which it can accept connections to PostgreSQL. In the file pg_hba.conf you need to add a line at the very end, similar to the previous ones, specifying from which address the ERP USERSIDE user can connect. But if your PostgreSQL is located on the same server as USERSIDE - there is no need to make any adjustments to these files.

Redis

The Debian 12 standard repository includes Redis version 7.0.15. This version is suitable for running ERP USERSIDE.

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 because it focuses on speed of request processing and extra steps like encryption are not applied), you need to create a really long and complex password, for example, using the openssl utility 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 substitute this generated string in place of the word MYPASSWORDHERE. Write it down. Then in the settings you will specify this string as the Redis password.

Specify the generated passphrase hash in the Redis configuration file:

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

where instead of MYPASSWORDHERE specify the hash of the passphrase received earlier.

It is also necessary to disable timeout (on some versions of Redis it is enabled):

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

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

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

RabbitMQ

The Debian 12 standard repository includes an older version of RabbitMQ 3.10. You can use it - it is supported. However, this version is relatively old and your best bet is to install a newer version from alternative repositories. The official RabbitMQ website has quite detailed information on installing RabbitMQ for each operating system.

Adding alternative repositories

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

curl -1sLf https://dl.cloudsmith.io/public/rabbitmq/rabbitmq-erlang/gpg.E495BB49CC4BBE5B.key | sudo gpg --dearmor | sudo tee /usr/share/keyrings/rabbitmq-erlang-archive-keyring.gpg > /dev/null
curl -1sLf https://dl.cloudsmith.io/public/rabbitmq/rabbitmq-server/gpg.9F4587F226208342.key | sudo gpg --dearmor | sudo tee /usr/share/keyrings/rabbitmq-server-archive-keyring.gpg > /dev/null

sudo tee /etc/apt/sources.list.d/rabbitmq.list <<EOF
deb [signed-by=/usr/share/keyrings/rabbitmq-erlang-archive-keyring.gpg] https://dl.cloudsmith.io/public/rabbitmq/rabbitmq-erlang/deb/debian $(lsb_release -cs) main
deb-src [signed-by=/usr/share/keyrings/rabbitmq-erlang-archive-keyring.gpg] https://dl.cloudsmith.io/public/rabbitmq/rabbitmq-erlang/deb/debian $(lsb_release -cs) main
deb [signed-by=/usr/share/keyrings/rabbitmq-server-archive-keyring.gpg] https://dl.cloudsmith.io/public/rabbitmq/rabbitmq-server/deb/debian $(lsb_release -cs) main
deb-src [signed-by=/usr/share/keyrings/rabbitmq-server-archive-keyring.gpg] https://dl.cloudsmith.io/public/rabbitmq/rabbitmq-server/deb/debian $(lsb_release -cs) main
EOF

sudo apt update

Installation

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

Do the next two rows one at a time!

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 we need to create users. We recommend to use three different users: for server administration (full rights), for userside and modules (full rights but no administrative rights) and web-stomp user for websocket (minimal rights to read certain broker objects). But you can only create two: an admin, which will also be used for userside, and a user for websocket. These must necessarily be at least two different users, since the password for the websocket user is passed to the browser and can be easily read by the user. The following will show an example for the recommended three users.

Create a user for administration RabbitMQ. This example uses the username admin and password password. The user is assigned the administrator tag immediately after creation, giving the user maximum administrator rights, and then set permissions on the vhost / allowing full access to configure, write and read everything within that vhost*.

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

Create a user on behalf of which ERP USERSIDE and modules will run. Example for the user name userside (there is no 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 WebSTOMP user. You will need it to use notifications via WebSocket. Instead of websock-user you can specify a different user name. Instead of websock-password, specify your password, but this password will be passed in the clear to the browser, so don't make it look like other passwords:

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

Caution!: You will need to specify the WebSTOMP username and password in the settings in the USERSIDE interface (Menu: Settings - Main - Websocket).

* vhost is a virtual host inside RabbitMQ that allows you to differentiate between different applications using the same server. Like, for example, different databases on the same RDBMS server. The default vhost is named / and almost always this is enough for you. But if you plan, for example, to run multiple copies of ERP USERSIDE on the same server, then for each copy you will need to create a different vhost and, accordingly, users for it. See official guide for details.

Restart the rabbitmq service:

sudo systemctl restart rabbitmq-server

Management

One of the commands above installs a management module in RabbitMQ that provides a convenient WEB interface to monitor, diagnose, and manage the RabbitMQ server. With the help of this module you can monitor the server, monitor the number of messages in the queues and other states. All this can be done using the console utility rabbitmqctl, but using the WEB-interface can be much more clear and convenient.

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

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

PHP

Alternative repository

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}

Note: if you are installing an environment for 3.19, you should use PHP8.3 instead of PHP8.1 here and below.

If you plan to use LDAP, you need to install the php-ldap extension:

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 commands make changes to the configuration files. Remember to change them if you have installed PHP8.3.

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@^;request_terminate_timeout =.*@request_terminate_timeout = 300@" /etc/php/8.1/fpm/pool.d/www.conf

sudo systemctl restart php8.1-fpm

NGINX

Alternative official repository

The version of NGINX supplied 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, then 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 install -y nginx

Setting

NGINX should run as the www-data user - the php-fpm www-pool 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 default system directory /var/www/userside. If you wish to install ERP USERSIDE in a different directory, please remember to fix it in all subsequent examples. In order not to make a mistake, we recommend to use exactly the /var/www/userside directory.

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

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

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/ /index.php$is_args$args;
    }

    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;  # Для USERSIDE 3.19 использовать php8.3-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 other things. This topic is beyond the scope of this manual.

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

Check the configuration and if it is ok reload nginx:

sudo nginx -t && sudo systemctl restart nginx

Python

Debian 12 has Python 3.11 in its default repository - this is sufficient, so no alternative repositories are needed. But if you have a version lower than 3.9 on your host, you should be sure to install additionally a more recent version of Python.

Installing the necessary packages

sudo apt install -y python3-dev python3-pip python3-venv libffi-dev pkg-config

Supervisor

sudo apt install -y supervisor

Downloading and running the installer

Set up after installation

Configuration of system services

After installation, copy the sample configuration files of the system services and adjust 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
sudo -H ./venv/bin/pip install -U -r requirements.txt

Description

Requirements

3.19 (beta)

3.18 (current stable)

Main Agreements

Installing the required components

PostgreSQL

Alternative official repository

Installation

Setting

Redis

Installation

Setting

RabbitMQ

Adding alternative repositories

Installation

Installing the necessary add-ons

Setting

Management

PHP

Alternative repository

Installation

Setting

NGINX

Alternative official repository

Installation

Setting

Python

Installing the necessary packages

Supervisor

Downloading and running the installer

Set up after installation

Configuration of system services

Install the necessary dependencies for usm_poller

Launching the supervisor

Immediately after installation

System upgrade

Upgrade process

System maintenance

Backup

Restore from backup

DUMP

SQL-script

After database restoring

RabbitMQ monitoring