Установка для версии 3.17

en | ru

ВНИМАНИЕ: Данная инструкция актуальна для версий ERP USERSIDE 3.11-3.17. Для версий 3.10 и ниже - используйте отдельную инструкцию по установке для 3.10.

Описание

В целях упрощения будут рассмотрены команды для операционной системы Linux Debian 11. Для опытных системных администраторов не составит труда использовать аналогичные команды для другой операционной системы. Если же вы не чувствуете себя уверено в администрировании операционных систем, то мы рекомендуем вам использовать операционную систему Debian либо Ubuntu Server. Из-за их простоты, а также по причине того, что наша техническая поддержка значительно лучше разбирается в Debian-подобных дистрибутивах. Вероятность подсказать что-либо не касающееся ERP USERSIDE, но касающееся администрирования операционной системы, будет значительно выше, если у вас будет Debian или подобный дистрибутив на его основе.

С другой стороны, если вы опытный системный администратор и имеете навыки и опыт работы с Docker, возможно для вас будет более удобным вариант использования готового окружения на базе Docker-образов, которые мы подготовили специально, включив в них всё необходимое для работы ERP USERSIDE. В этом случае вам не придется ничего настраивать, кроме как выполнить простые настройки Docker-бандла.

Данная инструкция целиком повторена на тестовом сервере Debian 10 и этот процесс записан в виде скринкаста. Может быть кому-то будет полезно: https://youtu.be/Zls7MA1rV6Q

Требования

Для работы ERP USERSIDE необходимы различные системные приложения и службы, такие как интерпретатор языка PHP с набором расширений, WEB-сервер, система управления базами данных и прочие. В этом разделе будут перечислены такие требования в зависимости от версии ERP USERSIDE.

Также обратите внимание, что ваша операционная система должна быть сконфигурирована с корректным часовым поясом и локалью. От этого зависит правильность отображения информации и корректность сортировки.

Список требуемых расширений PHP содержит все расширения, не входящие в состав ядра PHP. Часть из этих расширений может поставляться вместе с основным пакетом PHP либо в составе пакета php-common, другая же часть должна быть установлена дополнительно.

3.16, 3.17

• PHP: 7.2 - 7.4
• Расширения PHP: ctype, gd, json, libxml, mbstring, openssl, pdo, pdo_pgsql, posix, simplexml, snmp, sockets, zlib, pcntl
• Дополнительные расширения PHP: ldap, soap
• Python: 3.7+
• Модули Python: pip, virtualenv
• PostgreSQL: 10+
• Redis: 5+
• RabbitMQ: 3.8+
• Supervisor

3.15

• PHP: 7.1 - 7.4
• Расширения PHP: ctype, gd, json, libxml, mbstring, openssl, pdo, pdo_pgsql, posix, simplexml, snmp, sockets, zlib
• Дополнительные расширения PHP: ldap, soap
• PostgreSQL: 10+
• Redis: 5+

3.14

• PHP: 7.1 - 7.3
• Расширения PHP: ctype, gd, json, libxml, mbstring, openssl, pdo, pdo_pgsql, posix, simplexml, snmp, sockets, zlib
• Дополнительные расширения PHP: ldap, soap
• PostgreSQL: 10+
• Redis: 5+

3.13

• PHP: 7.1 - 7.3
• Расширения PHP: ctype, gd, json, libxml, mbstring, openssl, pdo, pdo_pgsql, posix, simplexml, snmp, sockets, zlib
• Дополнительные расширения PHP: ldap, soap
• PostgreSQL: 9.6+
• Redis: 5+

3.12

• PHP: 7.0 - 7.1
• Расширения PHP: ctype, gd, json, libxml, mbstring, openssl, pdo, pdo_pgsql, posix, simplexml, snmp, sockets, zlib
• Дополнительные расширения PHP: ldap, soap
• PostgreSQL: 9.5+

3.11

• PHP: 5.6 - 7.1
• Расширения PHP: ctype, gd, json, libxml, mbstring, openssl, pdo, pdo_pgsql, posix, simplexml, snmp, sockets, zlib
• Дополнительные расширения PHP: ldap, soap
• PostgreSQL: 9.5+
• MySQL: 5.6 - 5.7

Основные договорённости

Каталог, в который устанавливается ERP USERSIDE - /var/www/userside. Внутри этого каталога должен быть подкаталог userside3, который является корневым каталогом для WEB-сервера. Если вы хотите использовать другой каталог для ERP USERSIDE, не забывайте вносить соответствующие исправления во все примеры из данной инструкции.

Создайте каталог:

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

Вам необходимо выделить доменное имя для ERP USERSIDE. В примерах ниже используется userside.mycompany.com, но вам необходимо будет заменить его на свое.

Установка необходимых компонентов

Установка будет показана для последней актуальной на данный момент версии ERP USERSIDE 3.16. Для остальных версий вы можете самостоятельно изменить приведенные команды, чтобы добиться установки необходимого набора приложений определенных версий. Также обратите внимание, что в некоторых компонентах нет необходимости для других версий ERP USERSIDE.

Сперва установите утилиты, которые будут необходимы далее в процессе установки. Они необходимы для любой верии ERP USERSIDE. Вы можете копировать строки по одной и вставлять их в командную строку вашей операционной системы.

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

Следующие строки скопируйте и вставьте целиком:

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)-security contrib non-free
EOL

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

PostgreSQL

Альтернативный официальный репозиторий

Чтобы иметь возможность всегда устанавливать и обновляться до последней версии PostgreSQL, добавьте в вашу операционную систему альтернативный официальный репозиторий, выполнив команды:

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

Если у вас другая операционная система, вы можете найти необходимые команды для нее на официальном сайте PostgreSQL.

Шаг с добавлением альтернативного репозитория здесь и далее необязательный, но только при условии, что в основном репозитории вашей операционной системы находятся пакеты тех версий, которые попадают в диапазон требуемых для устанавливаемой версии ERP USERSIDE.

Установка

Перед установкой PostgreSQL в вашей операционной системе должна быть установлена ваша местная локаль и корректный часовой пояс. Это можно сделать и позже, но будет проще, если это будет сделано до установки. Выполните следующую команду, чтобы убедиться, что нужная локаль присутствует:

locale -a

Если среди перечисленных нет вашей местной локали, то установите ее. Для этого достаточно отредактировать файл /etc/locale.gen убрав комментарии перед строкой (строками) с нужной локалью, а затем выполнить команду:

sudo locale-gen

Если вам нужно изменить локаль по умолчанию, то выполните:

sudo dpkg-reconfigure locales

Чтобы изменить часовой пояс, выполните:

sudo timedatectl set-timezone Europe/Kyiv

Теперь можно перейти к установке PostgreSQL:

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

Настройка

Создайте пользователя (роль) и базу данных для ERP USERSIDE. В примере ниже создается пользователь с именем userside и база данных с таким же именем. Затем к базе данных подключается расширение PostGis, необходимое для манипуляции над геометрическими данными. После выполнения первой строки, вам необходимо будет дважды ввести пароль для нового пользователя - запишите этот пароль, он понадобится вам далее для установки 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"

Если ваш PostgreSQL установлен на другом сервере, то вам необходимо будет внести коррекции в файлы postgresql.conf и pg_hba.conf, расположенные в каталоге /etc/postgresql/14/main/. В файле postgresql.conf необходимо раскомментировать и изменить значение параметра listen_addresses, указав там все IP-адреса интерфейсов сервера, на которых он может принимать подключения к PostgreSQL. В файле pg_hba.conf необходимо в самом конце добавить строку по аналогии с предыдущими, указывающую, с какого адреса может подключаться пользователь ERP USERSIDE. Но если ваш PostgreSQL расположен на том же сервере, что и PHP и всё остальное - нет необходимости вносить какие либо корректировки в этот файл.

Тонкая настройка сервера PostgreSQL

Обратитесь к разделу Тонкая настройка.

Redis

Альтернативный способ установки

Стандартный репозиторий Debian 10 включает версию Redis 5.0.3, выпущенную в декабре 2018 года. Эта версия подходит для работы ERP USERSIDE. Если вы хотите установить последнюю версию из 6-й ветки, вам придется собрать Redis вручную. Если у вас нет опыта в этом, то просто установите Redis как показано ниже - этого вполне достаточно. Если вы используете Ubuntu server, то можете воспользоваться официальным PPA-репозиторием.

Информацию о ручной сборке Redis и о PPA-репозитории вы можете найти на официальном сайте Redis.

Установка

sudo apt install -y redis-server

Настройка

По умолчанию Redis принимает подключения без пароля, но мы настоятельно рекомендуем установить пароль. Так как пароль передается в открытом виде (Redis не предусматривает шифрования, т.к. делает упор на скорость обработки запросов и лишние этапы вроде шифрования не применяются), вам нужно создать действительно длинный и сложный пароль. Это можно сделать, например, используя утилиту sha256sum следующим образом:

echo "какая-то уникальная длинная фраза" | sha256sum

На выходе вы получите sha256 хэш, который и будете использовать в качестве настоящего пароля. Далее нужно будет вместо слова MYPASSWORDHERE подставить именно этот ваш пароль. Запишите его.

Укажите этот пароль в конфигурационном файле Redis:

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

где MYPASSWORDHERE - и есть ваш пароль Redis.

Также необходимо отключить таймаут (на некоторых версиях Redis он включен):

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

Перезапустите Redis и убедитесь, что он работает (в ответ должны получить PONG):

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

RabbitMQ

Необходимо только для версии 3.16 и более новой.

Стандартный репозиторий Debian 10 включает старую, более не поддерживаемую версию RabbitMQ 3.7. Поэтому добавление альтернативных репозиториев является обязательным в этом случае. На официальном сайте RabbitMQ находится достаточно подробная информация по установке RabbitMQ для каждой операционной системы.

Установка

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

Следующий блок скопируйте и вставьте целиком в командную строку

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

Установка необходимых дополнений

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

Настройка

Скопируйте и вставьте целиком следующий блок:

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

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

Теперь нужно создать пользователей. Мы рекомендуем использовать три различные учетные записи: для администрирования сервера (полные права), для userside и модулей (полные права но без административных) и пользователя web-stomp для websocket (минимальные права на чтение определенных объектов брокера).

Создайте пользователя для администрирования RabbitMQ. В данном примере используется имя пользователя admin и пароль password. Пользователю сразу после создания присваивается тэг administrator, наделяющий пользователя максимальными правами администратора и затем устанавливаются разрешения для vhost / позволяющие полный доступ к конфигурированию, записи и чтению всего в пределах этого vhost*.

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

Создайте пользователя, от имени которого будут работать ERP USERSIDE и модули. Пример для имени пользователя userside (наделять админскими правами этого пользователя не нужно):

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

Создайте пользователя для модуля WebSTOMP. Он понадобится для использования уведомлений через WebSocket (начиная с версии 3.17). Вместо websock-user вы можете указать другое имя пользователя, но мы рекомендуем оставить это. Вместо websock-password можно указать пароль, но этот пароль будет передаваться в открытом виде в браузер, так что слишком сложным делать его не имеет смысла:

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

* vhost - это виртуальный хост внутри RabbitMQ, позволяющий разграничить различные варианты использования одного и того же сервера разными приложениями. Как, например, разные базы данных на одном сервере СУБД. vhost по умолчанию имеет имя / и почти всегда вам этого достаточно. Но если вы планируете, например, запустить несколько копий ERP USERSIDE на одном сервере, то для каждой копии вам нужно будет создать свой vhost и, соответственно, пользователей для него. Подробней обратитесь к официальному руководству.

Управление

Одна из команд, приведенных выше, устанавливает в RabbitMQ модуль управления, предоставляющий удобный WEB-интерфейс для мониторинга, диагностики и управления сервером RabbitMQ. При помощи этого модуля можно осуществлять мониторинг сервера, следить за количеством сообщений в очередях и другими состояниями. Всё это можно делать и используя консольную утилиту rabbitmqctl, но использование WEB-интерфейса может быть значительно наглядней и удобней. Если вам не нужен WEB-интерфейс для управления сервером, можете отказаться от установки модуля rabbitmq_management на этапе установки.

По умолчанию WEB-интерфейс управления доступен по адресу http://userside.mycompany.com:15672

Подробнее о модуле управления можно прочитать на официальном сайте RabbitMQ.

PHP

Альтернативный репозиторий

Если ваша операционная система в своем стандартном репозитории пакетов имеет необходимую версию PHP, то можно установить PHP и расширения напрямую из основного репозитория операционной системы. Например, версия Debian-11 (Bullseye) в своем стандартном репозитории содержит PHP версии 7.4, который вполне подходит для ERP USERSIDE 3.16 и 3.17.

Однако, если версия вашей операционной системы более старая, то нужных версий пакетов там может просто не оказаться. В таком случае можно добавить в вашу операционную систему альтернативный репозиторий. Выполните команды, приведенные ниже, чтобы добавить в систему альтернативный репозиторий:

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

Установка

Выполните следующие команды:

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

Если вы планируете использовать LDAP, необходимо установить расширение php-ldap:

sudo apt install -y php7.4-ldap

Если вы планируете использовать отправку SMS используя TurboSMS, также понадобится расширение php-soap:

sudo apt install -y php7.4-soap

Настройка

Далее приведены команды, вносящие изменения в файлы конфигурации.

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

Тонкая настройка

По умолчанию в пуле PHP-FPM запускается 4 процесса, чтобы обеспечить возможность запуска на любом, даже самом слабом сервере. Это означает, что одновременно могут обрабатываться только 4 запроса, остальные будут ждать в очереди. Нужно оптимизировать пул PHP-FPM таким образом, чтобы количество работающих процессов покрывало нужды в использовании системы, а также было достаточное количество резервных процессов, которые могут быть дополнительно запущены автоматически менеджером процессов.

Весь процесс настройки описан в разделе Тонкая настройка.

NGINX

Альтернативный официальный репозиторий

Версия NGINX, поставляемая в репозитории Debian, подходит для использования и нет необходимости в добавлении альтернативного репозитория. Однако, если вам хочется всегда иметь последнюю версию, то выполните следующие строки, чтобы добавить в операционную систему официальный репозиторий nginx:

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

Если у вас другая операционная система, вы можете найти необходимые команды для нее на официальном сайте NGINX: https://docs.nginx.com/nginx/admin-guide/installing-nginx/installing-nginx-open-source/

Установка

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

Настройка

NGINX должен работать от имени пользователя www-data - от имени этого же пользователя работает www-пул php-fpm:

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

Следующий пример настройки подразумевает, что ERP USERSIDE будет установлен в стандартный каталог системы /var/www/userside. Если вы желаете установить ERP USERSIDE в другой каталог, пожалуйста, не забывайте исправлять его во всех последующих примерах. Чтобы не ошибиться, мы рекомендуем использовать именно каталог /var/www/userside.

В этом каталоге будет располагаться web-root, то есть файлы, доступные через протокол http.

Теперь отредактируйте файл /etc/nginx/conf.d/default.conf. Либо удалите его и создайте новый файл с произвольным именем, например /etc/nginx/conf.d/userside.conf. В любом случае, не зависимо от вашего выбора, содержимое файла должно быть следующим (вместо 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;
    }
}

Также, возможно, вы захотите настроить SSL и что-либо еще. Эта тема выходит за рамки данной инстуркции.

Если Вы установили RabbitMQ на другом сервере, либо изменили значение порта WebSTOMP с 15674 на какой-то другой, то укажите IP-адрес сервера с RabbitMQ и номер порта в строке proxy_pass http://127.0.0.1:15674/ws;. Протокол должен оставаться http. Путь должен оставаться /ws.

Проверьте конфигурацию и если она в порядке перезагрузите nginx:

sudo nginx -t && sudo systemctl restart nginx

Python

Debian 11 в стандартном репозитории содержит Python 3.9 - этого вполне достаточно, поэтому никакие альтернативные репозитории не нужны.

Установка

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

Supervisor

Необходимо только для версии 3.16 и более новой.

Установка

sudo apt install -y supervisor

Загрузка и запуск инсталлятора

См. также: Справку по инсталлятору

1. перейти в каталог системы

cd /var/www/userside

2. загрузить скрипт-инсталлятор

sudo -u www-data php -r "copy('https://my.userside.eu/install', 'userside_install.phar');" 

3. запустить инсталлятор

sudo -u www-data php userside_install.phar install

В процессе работы инсталлятор проверяет соответствие техническим требованиям, запрашивает параметры доступа и проверяет соединения со службами сервера.

Вы можете ввести любой доступный вам номер версии ERP USERSIDE для установки. Для этого можете ввести порядковый номер версии из списка (он содержит только последние версии каждой ветки) либо ввести номер версии целиком, если ее нет в списке.

По окончанию работы инсталлятора будет выведено сообщение об успешной установке.

Если вы произвели установку не от имени пользователя веб-сервера, то обязательно после окончания установки сделайте его владельцем всех файлов userside рекурсивно!

sudo chown -R www-data:www-data /var/www/userside
sudo chmod -R u=rwX,g=rwX,o=r /var/www/userside

Настройка после установки

Планировщик

Скопируйте и вставьте в командную строку следущие строки, чтобы добавить запуск планировщика в системном CRON:

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

Фоновые процессы ядра

Необходимо только для версии 3.16 и более новой.

Фоновые процесс ядра находятся в постоянном ожидании сообщений от брокера RabbitMQ. Через эти сообщения передаются задания либо результаты работы других воркеров.

Необходимо настроить автоматический запуск и контроль работы воркеров ядра. Для этого используется Supervisor. Создайте конфигурацию запуска службы супервизора скопировав целиком следующий блок и вставив его в командную строку:

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

Теперь нужно перезапустить супервизор:

sudo systemctl restart supervisor

Управление супервизором происходит при помощи утилиты supervisorctl. Например, чтобы вывести список всех процессов, запущенных и контролируемых супервизором, можно выполнить команду:

sudo supervisorctl status

Чтобы перезапустить воркеры ядра (us-core-worker), можно выполнить команду:

sudo supervisorctl restart us-core-worker:*

Более подробно о командах и способе использования супервизора можно прочитать в официальной документации.

Фоновые процессы микросервиса поллера

Необходимо только для версии 3.16 и более новой.

Микросервис поллера — это фоновые процесс, выполняющий команды взаимодействия с оборудованием. Файлы микросервиса поставляются вместе с ERP USERSIDE и расположены в /var/www/userside/microservice/poller.

Установка

Поллер реализован на языке программирования Python и требует для своей работы дополнительных модулей. Для этого лучше всего использовать виртуальное окружение Python. В этом случае все расширения будут устанавливаться в локальный подкаталог, что исключит любые конфликты в системе и позволит более удобно и просто оперировать этими расширениями в будущем (обновление версий и т.д.).

Выполните следующие команды, чтобы настроить виртуальное окружение:

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

Настройка

В составе поллера поставляется пример файла настроек супервизора. Скопируйте его как рабочий файл.

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

Перезапустите супервизор

sudo systemctl restart supervisor

Проверьте, что всё запустилось корректно

sudo supervisorctl status

Если возникли проблемы с запуском, попытайтесь запустить микросервис поллера вручную и проанализировать вывод

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

Сразу после установки

На этом установка ERP USERSIDE закончена. Теперь вы можете выполнить следующие шаги:

• Откройте страницу системы http://userside.mydomain.com/oper/ и выполните вход (по умолчанию имя пользователя: Admin, пароль: 1234).
• Выполните основные настройки в разделе: Настройка - Основная.
• Настройте взаимодействие с биллингом в соответствии с инструкциями.
• Ознакомьтесь с инструкциями на странице: С чего начать?.
• Желательно ограничить доступ к файлу API "/var/www/userside/userside3/api.php" с определенных IP-адресов.

Обновление системы

Технически возможно любое сквозное обновление, начиная с версии ERP USERSIDE 3.11 до последней версии. Однако бывают ситуации, когда при таком обновлении возникают проблемы с миграциями данных. Вероятней всего это возникает на старых системах, в которых данные накапливались долгие годы (начиная с обновления на версию 3 ERP USERSIDE). Поэтому мы рекомендуем именно поэтапное обновление системы. Если у вас 3.11, то сначала обновитесь до последней 3.12, затем 3.13 и т.д. Обратите внимание, что для каждой версии разные системные требования (см. выше), но большинство из них не ограничены версией сверху. То есть, если у вас 3.11 и вы хотите обновиться до 3.16, то не смотря на то, что вы будете выполнять поэтапное обновление, вы можете сразу установить последнюю версию PostgreSQL, Redis, RabbitMQ и т.д. Единственный момент, который придется учесть — версии PHP. Разные версии ERP USERSIDE поддерживают различный диапазон версий PHP. К сожалению, избежать этого нельзя, т.к. например, мы не тестировали ERP USERSIDE 3.14 на версии PHP 7.4 потому как на тот момент ее просто не существовало, поэтому гарантировать работу на этой версии мы просто не можем. Но диапазон поддерживаемых версий PHP довольно широк, чтобы не приходилось под каждую версию ERP USERSIDE устанавливать новую версию PHP. Например, чтобы обновиться с 3.11 до 3.16 вам понадобится всего несколько шагов:

• обновить PHP до версии 7.1 и на этой версии можно обновляться аж до 3.15. Также установите все необходимые зависимости сразу для версии 3.16
• после обновления до 3.15 обновите версию PHP до 7.4 и обновитесь до 3.16.

Мы рекомендуем сделать копию системы для безопасного проведения обновления. Обратитесь к разделу HOWTO: Клонирование USERSIDE. Вы всегда можете удалить копию и начать сначала. Это просто и безопасно. Но если вы желаете обновить работающую систему, то выполняйте его в моменты наименьшей нагрузки с запасом по времени, необходимым для аварийного восстановления, если вдруг что-то пойдет не так. Всегда обязательно делайте резервную копию базы данных и файлов перед обновлениями. Если обновление будет прервано, особенно на этапе миграции данных, то есть риск того, что восстановить корректно данные будет очень непросто или даже невозможно. В общем, ответственность за наличие актуальной резервной копии лежит целиком на вас.

Возможно перед обновлением вам понадобится обновить PostgreSQL. Обратитесь к нашей инструкции по обновлению PostgreSQL для проведения этой процедуры предже чем начнете процесс обновления ERP USERSIDE.

Процесс обновления

После создания копии системы или, как минимум, полной резервной копии рабочей системы, если вы не хотите делать клон, вам достаточно запустить команду инсталляции:

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

Далее в интерактивном режиме выбрать версию для обновления, указать недостающие параметры конфигурации для новой версии, если таковы имеются и подождать, пока обновление завершится. После обновления обязательно проверяйте хотя бы базовую работоспособность системы. Особенно это касается поэтапного обновления: не обновляйтесь на следующий этап, если текущий завершился с ошибкой или система перестала работать корректно.

Для версии 3.16 и новее.

После обновления могут измениться зависимости микросервиса поллера. Выполняйте эту команду каждый раз после обновления, даже если чаще всего она ничего не делает:

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

После обновления нужно обязательно перезапустить фоновые процессы, управляемые супервизором, чтобы начали работать обновленные файлы:

sudo systemctl restart supervisor

Обслуживание системы

Для поддержания системы в рабочем состоянии и обеспечения надежной ее работы в будущем рекомендуется выполнять несколько простых дейсвтий:

• периодически создавать резервную копию базы данных
• периодически создавать резервную копию загруженных файлов (это можно сделать просто архивируя каталог /var/www/userside/var/attachments и файл .env)
• периодически наблюдать за производительностью сервера (при помощи htop, atop) и брокера RabbitMQ и принимать решения о масштабировании пулов fpm, фоновых процессов ядра и микросервисов

Резервное копирование

Установите периодическое резервное копирование базы данных и пользовательских файлов. Желательно минимум раз в сутки в моменты наименьшей нагрузки на сервер. В PostgreSQL существует два способа создать резервную копию базы данных: dump и sql-script. У каждого из них есть свои преимущества и недостатки. Первый создает безопасный дамп базы данных целиком, а второй создает SQL-скрипт, выполняя который можно восстановить как структуру так и данные. Рекомендуем обратиться к документации по использованию команды pg_dump для выбора более подходящего для вас способа или набора параметров.

Ниже приведены две команды для создания резервной копии базы данных — выбирайте одну из них и добавляйте в ваш 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

Для создания минимальной резервной копии файлов можно использовать следующую команду (для версии 3.15 и новее):

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

Этих файлов вместе с базой данных будет достаточно для восстановления работы USERSIDE. Но вы можете выполнять резервное копирование всего каталога /var/www/userside для большей надежности.

Восстановление из резервной копии

Для восстановления из дампа используется команда pg_restore. Документация по использованию pg_restore. Для восстановления из SQL-скрипта используется утилита psql. Документация по использованию psql.

DUMP

Дамп содержит целиком базу данных со всеми ее элементами. Поэтому перед восстановлением базы данных из дампа её не должно существовать на сервере — удалите базу данных перед восстановлением из дампа. Также важно, чтобы пользователь базы данных (владелец всех элементов) уже существовал — создайте его перед восстановлением, если вы восстанавливаете базу данных на новом сервере, где нужного пользователя еще нет.

Также обратите внимание, что структура дампа может быть несовместима между разными версиями PostgreSQL. Это не обязательно так, но вполне вероятно.

Для восстановления из дампа используйте команду:

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

Обратите внимание, что имя базы данных в команде обязательно должно быть postgres, так как имя восстанавливаемой базы данных берется из дампа.

SQL-script

Восстановить базу данных из SQL-скрипта можно при помощи команды:

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

База данных перед выполнением этой команды уже должна существовать, но при этом быть пустой. Также должен существовать пользователь (владелец) объектов базы данных.

После восстановления базы данных

После восстановления базы данных любым способом, необходимо очистить кэш ERP USERSIDE, т.к. в кэше теперь находятся данные, отличные от данных в базе. Перейтите в каталог /var/www/userside и выполните команду очистки кэша:

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

Если версии файлов USERSIDE и дампа базы отличаются, то после восстановления базы данных из бекапа необходимо привести версию USERSIDE к соответствующей данным. Для этого в каталоге /var/www/userside выполните команду:

sudo -u www-data php userside_install.phar repair

Обслуживание PostgreSQL

Архитектура PostgreSQL такова, что при операциях, изменяющих данные в таблицах, всегда создается новая копия этих данных, а старые помечаются как "мёртвые" — это значительно ускоряет эти операции, но файлы базы данных со временем могут вырастать в объеме, что также может значительно сказываться на производительности.

По умолчанию в Postgres включена система автоматического вакуумирования, которая работает постоянно параллельно самой СУБД. Автоматическое вакуумирование производит удаление из файлов "мёртвых" кортежей, чтобы высвободившееся место могло быть повторно использовано новыми данными. Но такой режим вакуумирования не выполняет дефрагментацию файлов, оставляя их размер, как минимум, тем же.

В большинстве случаев автоматического вакуумирования вполне достаточно и мы не рекомендуем отключать автовакуум, чтобы ваши файлы не разрослись до огромных размеров, а работа базы не замедлилась в десятки или сотни раз.

Процедура полного вакуумирования, которую можно запустить вручную, производит дефрагментацию, уменьшая размер файлов базы данных. Но она выполняется с полной блокировкой таблиц! Процедуру полного вакуумирования (а также перестроения индексов) желательно выполнять во время наименьшей нагрузки на сервер при явной необходимости (если объем файлов базы данных слишком большой, в десятки или сотни раз превышает обычный объем). Во время этой процедуры таблицы базы данных будут заблокированы, так как эта процедура создает новые файлы с данными и переносит в них только "живые" данные. После этой процедуры также желательно выполнить процедуру перестроения индексов. Подробную информацию по вакуумированию и реиндексации вы можете найти в документации PostgreSQL.

Ниже приведены команды, которые являются псевдонимами одноимённым SQL-запросам. Если вам проще выполнять SQL-запросы вместо команд, обратитесь к документации по ссылкам выше.

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

Если вы запускали процедуру вакуумирования вручную ранее, то наверняка использовали параметр -j или --jobs для указания количества потоков. При использовании полного вакуумирования нежелательно использовать многопоточность во избежание взаимоблокировки таблиц.

Мониторинг RabbitMQ

Необходимо только для версии 3.16 и более новой.

В системе RabbitMQ management в наглядной форме отображаются графики с загруженностью очередей сообщений. Постоянно высокое или потенциально растущее количество сообщений в очередях говорит о необходимости увеличения количества фоновых процессов. Например, если в очереди с именем userside наблюдается постоянно большое количество сообщений (больше 10...20) то стоит добавить еще один экземпляр обработчика us-core-worker. Для этого отредактируйте файл супервизора /etc/supervisor/conf.d/us-core-worker.conf увеличив значение numprocs, а затем перезапустите супервизор.