Установка для версии 3.18: различия между версиями

Материал из WiKi - UserSide
Нет описания правки
 
(не показано 110 промежуточных версий 3 участников)
Строка 1: Строка 1:
'''ВНИМАНИЕ: Данная инструкция актуальна для версий ERP "UserSide" 3.11 и выше. Для версии ниже 3.11 - используйте отдельную инструкцию по [[Установка системы|установке]].
<languages/>
[[Installation_for_version_3.18|en]] | [[Установка_для_версии_3.18|ru]]


== Подготовительные работы ==
'''ВНИМАНИЕ: Данная инструкция актуальна для версий ERP USERSIDE 3.18'''
* [[Установка для версии 3.17|Инструкция для версии 3.11-3.17]]
* [[Установка для версии 3.10 и более ранних|Инструкция для версии 3.10 и ранее]].


* рекомендуется выполнять установку на любые Unix-системы. Рекомендуем использовать дистрибутивы Linux попроще и понадежнее, вроде Debian, CentOS или Ubuntu Server (FreeBSD тоже подойдет, если вы знаете, с чем имеете дело). Установка на Windows также возможна, но практика показала, что на *nix-системах производительность системы гораздо выше при тех же технических характеристиках сервера. Далее и везде в этой статье рассматривается пример установки на Linux Debian 9 Stretch с web-сервером nginx.
== Описание ==
В целях упрощения будут рассмотрены команды для операционной системы '''Linux Debian 12 (bookworm)'''. Для опытных системных администраторов не составит труда использовать аналогичные команды для другой операционной системы. Если же вы не чувствуете себя уверено в администрировании операционных систем, то мы рекомендуем вам использовать операционную систему '''Debian''' либо '''Ubuntu Server LTS'''. Из-за их простоты, а также по причине того, что наша техническая поддержка значительно лучше разбирается в Debian-подобных дистрибутивах. Вероятность подсказать что-либо не касающееся ERP USERSIDE, но касающееся администрирования операционной системы, будет значительно выше, если у вас будет Debian или подобный дистрибутив на его основе.


* убедитесь, что ваша система соответствует необходимым [[Технические требования|техническим требованиям]].
С другой стороны, если вы опытный системный администратор и имеете навыки и опыт работы с Docker, возможно для вас будет более удобным вариант использования готового окружения на базе Docker-образов, которые мы подготовили специально, включив в них всё необходимое для работы ERP USERSIDE. В этом случае вам не придется ничего настраивать, кроме как выполнить простые настройки Docker-бандла https://github.com/userside/userside-docker.


* установите postgresql-11, postgis-2.5, php7.2 ''(для Userside 3.13+ или php 7.1 для Userside 3.11, 3.12)'', redis, все необходимые расширения для PHP и веб-сервер, который вам больше нравится. Мы рекомендуем использовать асинхронный web-сервер nginx последних версий. Ниже показан пример для Debian 9 (Stretch). Для других дистрибутивов или операционных систем процесс может быть другим, в том числе значительно проще (для UbuntuServer 18 LTS):
== Требования ==
Для работы ERP USERSIDE необходимы различные системные приложения и службы, такие как интерпретатор языка PHP с набором расширений, WEB-сервер, система управления базами данных и прочие. В этом разделе будут перечислены такие требования в зависимости от версии ERP USERSIDE.


sudo apt update
Также обратите внимание, что ваша операционная система должна быть сконфигурирована с корректным часовым поясом и локалью. От этого зависит правильность отображения информации и корректность сортировки.
sudo apt install -y apt-transport-https lsb-release ca-certificates
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
wget --quiet -O - http://nginx.org/keys/nginx_signing.key | sudo apt-key add -
echo "deb http://nginx.org/packages/mainline/debian/ $(lsb_release -sc) nginx" | sudo tee -a /etc/apt/sources.list.d/nginx.list
echo "deb-src http://nginx.org/packages/mainline/debian/ $(lsb_release -sc) nginx" | sudo tee -a /etc/apt/sources.list.d/nginx.list
sudo wget -O /etc/apt/trusted.gpg.d/php.gpg https://packages.sury.org/php/apt.gpg
echo "deb https://packages.sury.org/php/ $(lsb_release -sc) main" | sudo tee -a /etc/apt/sources.list.d/php.list
sudo apt update
sudo apt remove -y nginx-common apache2
sudo apt autoremove -y
sudo apt install -y snmp-mibs-downloader postgresql-11 postgresql-11-postgis-2.5 nginx
sudo apt install -y php7.2-fpm php7.2-cli php7.2-common php7.2-curl php7.2-intl php7.2-json php7.2-mbstring php7.2-opcache php7.2-pgsql php7.2-readline php7.2-xml php7.2-zip php7.2-snmp php7.2-gd php7.2-soap
sudo download-mibs
 
* выполните настройку PHP: укажите свой часовой пояс, желаемый объем POST-данных (если 50 Мб мало - укажите ваше предпочитаемое значение) и максимальное время выполнения (если в будущем будет мало, сможете изменить); и базовую настройку nginx, выполнив следующие команды:


sudo sed -i "s@^;*date.timezone.*@date.timezone = Europe/Zaporozhye@" "/etc/php/7.2/fpm/php.ini"
Список требуемых расширений PHP содержит все расширения, не входящие в состав ядра PHP. Часть из этих расширений может поставляться вместе с основным пакетом PHP либо в составе пакета php-common, другая же часть должна быть установлена дополнительно.  
sudo sed -i "s@^;*date.timezone.*@date.timezone = Europe/Zaporozhye@" "/etc/php/7.2/cli/php.ini"
sudo sed -i "s@;cgi.fix_pathinfo=1@cgi.fix_pathinfo=0@" "/etc/php/7.2/fpm/php.ini"
sudo sed -i "s@post_max_size = 8M@post_max_size = 50M@" "/etc/php/7.2/fpm/php.ini"
sudo sed -i "s@upload_max_filesize = 2M@upload_max_filesize = 50M@" "/etc/php/7.2/fpm/php.ini"
sudo sed -i "s@^user.*;@user www-data www-data;@" "/etc/nginx/nginx.conf"
sudo sed -i "s@max_execution_time.*@max_execution_time = 120@" "/etc/php/7.2/fpm/php.ini"
sudo sed -i "s@max_input_time.*@max_input_time = 120@" "/etc/php/7.2/fpm/php.ini"
sudo sed -i 's@;*request_terminate_timeout.*@request_terminate_timeout = 120@' /etc/php/7.2/fpm/pool.d/www.conf


* создайте каталог, который будет является корнем web-сервера (root). При этом обратите внимание на то, что корнем самого приложения будет каталог '''/var/www/userside'''.
=== 3.18 ===
* PHP: 8.1
* Расширения PHP: ctype, gd, json, libxml, mbstring, openssl, pdo, pdo_pgsql, posix, simplexml, snmp, sockets, zlib, pcntl
* Дополнительные расширения PHP: ldap, soap
* Python: ''Необходим Python3 любой поддерживаемой на данный момент версии. Статус версий можно посмотреть здесь: "[https://devguide.python.org/versions/ Status of Python versions]". Рекомендуется использовать версию с состоянием "security" или "bugfix". Версии отмеченные как "end-of-life" не поддерживаются. Отмеченные как "feature" не рекомендуется использовать.''
* Модули Python: pip, venv
* PostgreSQL: 10+ (желательно 16)
* Redis: 5+ (желательно 7)
* RabbitMQ: 3.8+ (желательно 3.13)
* Supervisor


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


* создайте сайт для nginx (или отредактируйте имеющийся сайт по умолчанию). Для этого создайте файл /etc/nginx/conf.d/userside.conf и поместите в него текст:
Создайте каталог:
sudo mkdir -p /var/www/userside/userside3
sudo chown -R www-data:www-data /var/www/userside


server {
Вам необходимо выделить доменное имя для ERP USERSIDE. В примерах ниже используется userside.mycompany.com, но вам необходимо будет заменить его на свое. Пропишите это доменное имя в /etc/hosts, если оно отличается от имени хоста, на котором производистя установка.
    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.2-fpm.sock;
        fastcgi_index index.php;
        fastcgi_param SCRIPT_FILENAME $document_root$fastcgi_script_name;
        fastcgi_read_timeout 600;
        include      fastcgi_params;
    }
    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;
    }
}


* выполните [[Установка PostgreSQL|установку и/или настройку PostgreSQL и расширения Postgis]]
== Установка необходимых компонентов ==
Сперва установите утилиты, которые будут необходимы далее в процессе установки. Они необходимы для любой верии ERP USERSIDE. Вы можете копировать строки по одной и вставлять их в командную строку вашей операционной системы.


* выполните [[Установка Redis|установку и/или настройку Redis]]
Следующие строки скопируйте и вставьте целиком:
<pre>
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
</pre>


sudo systemctl restart postgresql.service
=== PostgreSQL ===
sudo systemctl restart nginx.service
==== Альтернативный официальный репозиторий ====
sudo systemctl restart php7.2-fpm.service
Мы настоятельно рекомендуем использовать последнюю версию PostgreSQL, так как это всегда положительно сказывается на скорости работы. Добавьте в систему официальный репозиторий Postgres:
<pre>
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
</pre>
Если у вас другая операционная система, вы можете найти необходимые команды для нее на [https://www.postgresql.org/download/ официальном сайте PostgreSQL].


=== Оптимизация пула PHP-FPM ===
==== Установка ====
'''Внимание!''' Перед установкой PostgreSQL в вашей операционной системе должна быть установлена ваша местная локаль и корректный часовой пояс! Это можно сделать и позже, но будет намного проще, если это будет сделано до установки PostgreSQL. Выполните следующую команду, чтобы убедиться, что нужная локаль присутствует:
locale -a


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


Сперва обязательно проведите оптимизацию PostgreSQL. Как это сделать - указано в [[Установка PostgreSQL#Тонкая настройка|соответствующем разделе]].
Если вам нужно изменить локаль по умолчанию, то выполните:
sudo dpkg-reconfigure locales


Далее, после того как оптимизация PostgreSQL выполнена, перейдите к оптимизации пула PHP-FPM. По умолчанию за настройку пула отвечает файл /etc/php/7.2/fpm/pool.d/www.conf
Чтобы изменить часовой пояс, выполните:
sudo timedatectl set-timezone Europe/Kyiv


Этот файл содержит несколько настроек менеджера процессов (PM), которые начинаются с <code>pm</code>
Теперь можно перейти к установке PostgreSQL:
sudo apt install -y postgresql-16 postgresql-16-postgis-3


Мы рекомендуем использовать динамический пул, так как на одном сервере работают и другие службы. В этом случае менеджер процессов будет управлять количеством процессов php-fpm в памяти автоматически, высвобождая ресурсы, если в них нет необходимости. По умолчанию менеджер процессов работает именно в этом режиме, но на всякий случай убедитесь, что это именно так: <code>pm = dynamic</code>
==== Настройка ====
Создайте пользователя и базу данных для ERP USERSIDE. В примере ниже создается пользователь с именем userside и база данных с таким же именем. Если ваша локаль не uk_UA, не забудьте изменить команду. Затем к базе данных подключается расширение PostGis, необходимое для работы с географическими данными. После выполнения первой строки, вам необходимо будет дважды ввести пароль для нового пользователя - запишите этот пароль, он понадобится вам далее для установки ERP USERSIDE
<pre>
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"
</pre>


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


Один процесс php-fpm занимает примерно 48 Мб в ОЗУ (это справедливо только для USERSIDE). Однако, если у вас слишком большой объем данных в USERSIDE, то это значение может быть несколько больше. Главное использовать не максимальное, а среднее значение. Ведь не все до единого запросы потребляют максимальное количество ОЗУ. Чтобы узнать, какое количество ОЗУ потребляют ваши процессы PHP-FPM, то в момент нормальной рабочей нагрузки на WEB-приложение USERSIDE, выполните команду:
=== Redis ===
Стандартный репозиторий Debian 12 включает версию Redis 7.0.15. Эта версия подходит для работы ERP USERSIDE.


  ps -eo rss,comm,cmd | grep php-fpm
==== Установка ====
  sudo apt install -y redis-server


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


  3304 php-fpm7.2      php-fpm: master process (/etc/php/7.2/fpm/php-fpm.conf)
  openssl rand --hex 32
41596 php-fpm7.2      php-fpm: pool www
36304 php-fpm7.2      php-fpm: pool www
  38516 php-fpm7.2      php-fpm: pool www


Здесь виден мастер-процесс PHP-FPM и три воркера - их порождает мастер и именно они обрабатывают WEB-запросы. В данном случае три воркера потребляют в среднем 38 Мб. Запоминаем это значение.
На выходе вы получите случайный набор из 32 байт в 16-ричном виде, который и будете использовать в качестве пароля. Далее нужно будет вместо слова '''MYPASSWORDHERE''' подставить эту сгенерированную строку. Запишите его. Далее в настройках вы будете указывать эту строку как пароль Redis.


Теперь необходимо узнать, сколько свободной оперативной памяти у нас есть. Делать это необходимо после оптимизации PostgreSQL и желательно в момент нормальной рабочей нагрузки. Выполните:
Укажите полученный хэш парольной фразы в конфигурационном файле Redis:


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


В результате вы получите приблизительно следующий вывод:
где вместо '''MYPASSWORDHERE''' укажите хэш парольной фразы поулченый ранее.


              total        used        free      shared  buff/cache  available
Также необходимо отключить таймаут (на некоторых версиях Redis он включен):
Mem:           996        147        331        124        516        581


Чтобы вычислить объем оперативной памяти, который можно использовать, воспользуемся формулой: available = total - (used + buff). В данном случае это 333 Мб.
sudo sed -i 's@^timeout .*@timeout 0@' /etc/redis/redis.conf


Весь этот объем оперативной памяти мы бы могли использовать для пула php-fpm. Но все же желательно взять от него около 80%, не более. В данном случае это примерно 266 Мб.
Перезапустите Redis и убедитесь, что он работает (в ответ должны получить PONG):
<pre>
sudo systemctl restart redis
redis-cli -h 127.0.0.1 -p 6379 -a MYPASSWORDHERE ping
</pre>


Теперь считаем количество воркеров. Один воркер потребляет в среднем 38 Мб, а объем свободной памяти 266 Мб. Всё это очень приблизительно, так как эти значения далеко не постоянны. Нам остается просто разделить объем свободной памяти на количество памяти, потребляемой одним воркером. Получим 266 / 38 = 7. Такое максимальное количество воркеров мы можем запустить.
=== RabbitMQ ===
Стандартный репозиторий Debian 12 включает старую версию RabbitMQ 3.10. Вы можете использовать ее — она поддерживается. Однако, эта версия относительно старая и лучшим вариантом будет установить новую версию из альтернативных репозиториев. На [https://www.rabbitmq.com/install-debian.html официальном сайте RabbitMQ] находится достаточно подробная информация по установке RabbitMQ для каждой операционной системы.


Указываем в качестве значения <code>pm.max_children = 7</code>.
==== Добавление альтернативных репозиториев ====
Следующий блок скопируйте и вставьте целиком в командную строку
<pre>
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


Далее необходимо настроить минимальное и максимальное количество воркеров, ожидающих соединеия. За это отвечают параметры <code>pm.min_spare_servers</code> и <code>pm.max_spare_servers</code> соответственно. Значения этих параметров подбираются "на глаз" и зависят от реального количества запросов, от их "тяжести" и многого другого. Для начала возьмем минимальное количество ожидающих воркеров примерно 25% от общего максимума (max_children), а максимальное примерно 50%.
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


pm.min_spare_servers = 2
sudo apt update
pm.max_spare_servers = 4
</pre>


Далее необходимо настроить количество воркеров, которое будет запущено при старте пула php-fpm. За это отвечает параметр <code>pm.start_servers</code> и его значение рассчитывается по формуле: min_spare_servers + (max_spare_servers - min_spare_servers) / 2. В нашем случае, это 3
==== Установка ====
<pre>
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


Итого, настройка менеджера процессов пула PHP-FPM будет следующей:
sudo apt install rabbitmq-server -y --fix-missing
</pre>


pm.max_children = 7
==== Установка необходимых дополнений ====
pm.min_spare_servers = 2
Следующие две строки выполняйте по одной за раз!
pm.max_spare_servers = 4
<pre>
pm.start_servers = 3
sudo rabbitmq-plugins enable rabbitmq_management --offline
sudo rabbitmq-plugins enable rabbitmq_web_stomp --offline
</pre>


Здесь важно отметить следующие моменты. В этих демонстрационных расчетах использовались данные сервера с объемом ОЗУ 1 Гб. В вашем же случае на реальном сервере максимальное количество воркеров может получиться очень большим - несколько сотен. Однако не стоит использовать такое большое количество воркеров, если у вас работает всего два оператора и никто больше не работает с USERSIDE. Лишние воркеры будут просто бесполезно занимать ОЗУ, которое могло быть использовано тем же PostgreSQL в мирных целях. Данные рекомендации помогут понять, какое максимальное количество воркеров можно использовать для максимальной утилизации системы, но если в таком количестве процессов, ожидающих http-запросы, нет смысла, то нет необходимости использовать его - просто понизьте его до разумных значений.
==== Настройка ====
Скопируйте и вставьте целиком следующий блок:
<pre>
sudo tee /etc/rabbitmq/rabbitmq.conf << EOF
listeners.tcp.default = 5672


Также рекомендуем наблюдать за файлом журнала php-fpm на предмет проблем с воркерами.
web_stomp.port = 15674
web_stomp.cowboy_opts.max_keepalive = 60
EOF
</pre>


tail -f /var/log/php7.2-fpm.log
Теперь нужно создать пользователей. Мы рекомендуем использовать '''три различных пользователя''': для администрирования сервера (полные права), для userside и модулей (полные права но без административных) и пользователя web-stomp для websocket (минимальные права на чтение определенных объектов брокера). Но вы можете создать только два: администратора, который также будете использоваться для USERSIDE, и пользователя для websocket. Это обязательно должны быть минимум два разных пользователя, так как пароль для websocket пользователя передается в браузер и может быть легко прочитан пользователем. Далее будет показан пример для рекомендуемых трех пользователей.  


Об этом могут говорить строки вроде следующей:
Создайте '''пользователя для администрирования''' RabbitMQ. В данном примере используется имя пользователя '''admin''' и пароль '''password'''. Пользователю сразу после создания присваивается тэг <code>administrator</code>, наделяющий пользователя максимальными правами администратора и затем устанавливаются разрешения для vhost <code>/</code> позволяющие полный доступ к конфигурированию, записи и чтению всего в пределах этого vhost*.
<pre>
sudo rabbitmqctl add_user "admin" "password"
sudo rabbitmqctl set_user_tags "admin" "administrator"
sudo rabbitmqctl set_permissions -p "/" "admin" ".*" ".*" ".*"
</pre>


WARNING: [pool www] server reached pm.max_children setting (5), consider raising it
Создайте '''пользователя, от имени которого будут работать ERP USERSIDE''' и модули. Пример для имени пользователя '''userside''' (наделять админскими правами этого пользователя не нужно):
<pre>
sudo rabbitmqctl add_user "userside" "password2"
sudo rabbitmqctl set_user_tags "userside" "monitoring"
sudo rabbitmqctl set_permissions -p "/" "userside" ".*" ".*" ".*"
</pre>


== Инсталлятор ==
<span id="websocket"></span>Создайте '''пользователя WebSTOMP'''. Он понадобится для использования уведомлений через WebSocket. Вместо '''websock-user''' вы можете указать другое имя пользователя. Вместо '''websock-password''' укажите свой пароль, но этот пароль будет передаваться в открытом виде в браузер, так что не делайте его похожим на остальные пароли:
<pre>
sudo rabbitmqctl add_user "websock-user" "websock-password"
sudo rabbitmqctl set_permissions -p "/" "websock-user" "^userside-stomp:id-.*" "" "^userside-stomp:id-.*"
</pre>


См. также: [[Инсталлятор]]
Внимание! Имя пользователя и пароль WebSTOMP вам нужно будет указать в настройках в интерфейсе USERSIDE (Меню: Настройки - Основные - Websocket).


[[Файл:Interactive-Install.png|center]]
''* vhost - это виртуальный хост внутри RabbitMQ, позволяющий разграничить различные варианты использования одного и того же сервера разными приложениями. Как, например, разные базы данных на одном сервере СУБД. vhost по умолчанию имеет имя / и почти всегда вам этого достаточно. Но если вы планируете, например, запустить несколько копий ERP USERSIDE на одном сервере, то для каждой копии вам нужно будет создать свой vhost и, соответственно, пользователей для него. Подробней обратитесь к [https://www.rabbitmq.com/vhosts.html официальному руководству].''


1) перейти в каталог системы ''(/var/www/userside)''
Перезапустите службу rabbitmq:
<pre>
sudo systemctl restart rabbitmq-server
</pre>


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


php -r "copy('https://my.userside.eu/install', 'userside_install.phar');"
По умолчанию WEB-интерфейс управления доступен по адресу http://userside.mycompany.com:15672


ЛИБО
Подробнее о модуле управления можно [https://www.rabbitmq.com/management.html прочитать на официальном сайте RabbitMQ].


скачать инсталлятор с личного кабинета https://my.userside.eu и положить его в каталог системы
=== PHP ===
==== Альтернативный репозиторий ====
3) запустить инсталлятор от имени пользователя, под которым работает web-сервер (www-data, но может быть и другим)
<pre>
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
</pre>


==== Установка ====
Выполните следующие команды:
<pre>
sudo apt install -y php8.1-{fpm,cli,common,curl,intl,mbstring,opcache,pgsql,readline,xml,zip,snmp,gd}
</pre>
Если вы планируете использовать LDAP, необходимо установить расширение php-ldap:
<pre>
sudo apt install -y php8.1-ldap
</pre>
Если вы планируете использовать отправку SMS используя TurboSMS, также понадобится расширение php-soap:
<pre>
sudo apt install -y php8.1-soap
</pre>
==== Настройка ====
<pre>
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
</pre>
=== NGINX ===
==== Альтернативный официальный репозиторий ====
Версия NGINX, поставляемая в репозитории Debian, полностью подходит для использования и нет необходимости в добавлении альтернативного репозитория. Однако, если вам хочется всегда иметь последнюю версию, то выполните следующие строки, чтобы добавить в операционную систему официальный репозиторий nginx:
<pre>
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
</pre>
Если у вас другая операционная система, вы можете найти необходимые команды для нее на официальном сайте NGINX: https://docs.nginx.com/nginx/admin-guide/installing-nginx/installing-nginx-open-source/
==== Установка ====
<pre>
sudo apt install -y nginx
</pre>
==== Настройка ====
<pre>
sudo sed -i "s@^user.*;@user www-data www-data;@" "/etc/nginx/nginx.conf"
sudo systemctl restart nginx
</pre>
Следующий пример настройки подразумевает, что ERP USERSIDE будет установлен в стандартный каталог системы <code>/var/www/userside</code>. Если вы желаете установить ERP USERSIDE в другой каталог, пожалуйста, не забывайте исправлять его во всех последующих примерах. Чтобы не ошибиться, мы рекомендуем использовать именно каталог <code>/var/www/userside</code>.
В этом каталоге будет располагаться web-root, то есть файлы, доступные через протокол http.
Теперь отредактируйте файл /etc/nginx/conf.d/default.conf. Либо удалите его и создайте новый файл с произвольным именем, например /etc/nginx/conf.d/userside.conf. В любом случае, не зависимо от вашего выбора, содержимое файла должно быть следующим (вместо userside.mycompany.com укажите свое доменное имя):
<pre>
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; }
}
</pre>
Также, возможно, вы захотите настроить SSL и что-либо еще. Эта тема выходит за рамки данной инстуркции.
Если Вы установили RabbitMQ '''на другом сервере''', либо изменили значение порта WebSTOMP с 15674 на какой-то другой, то укажите IP-адрес сервера с RabbitMQ и номер порта в строке <code>proxy_pass http://127.0.0.1:15674/ws;</code>. Протокол должен оставаться http. Путь должен оставаться /ws.
Проверьте конфигурацию и если она в порядке перезагрузите nginx:
sudo nginx -t && sudo systemctl restart nginx
=== Python ===
''Необходим Python3 любой поддерживаемой на данный момент версии. Статус версий можно посмотреть здесь: "[https://devguide.python.org/versions/ Status of Python versions]". Рекомендуется использовать версию с состоянием "security" или "bugfix". Версии отмеченные как "end-of-life" не поддерживаются. Отмеченные как "feature" не рекомендуется использовать.''
Если у вас на хосте неподдерживаемая версия ("end-of-life"), то нужно обязательно [[Python-update|установить дополнительно]] более свежую версию Python.
==== Установка необходимых пакетов ====
sudo apt install -y python3-dev python3-pip python3-venv libffi-dev pkg-config
=== Supervisor ===
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
  sudo -u www-data php userside_install.phar install


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


По окончанию работы инсталлятора будет выведено сообщение об успешной установке.
По окончанию работы инсталлятора будет выведено сообщение об успешной установке.
Строка 187: Строка 361:
Если вы произвели установку не от имени пользователя веб-сервера, то обязательно после окончания установки сделайте его владельцем всех файлов userside рекурсивно!
Если вы произвели установку не от имени пользователя веб-сервера, то обязательно после окончания установки сделайте его владельцем всех файлов userside рекурсивно!


== Настройка системы ==
sudo chown -R www-data:www-data /var/www/userside
sudo chmod -R u=rwX,g=rwX,o=r /var/www/userside


* открыть страницу системы '''<nowiki>http://userside.mydomain.com/oper/</nowiki>''' и убедиться в работоспособности системы ''(имя пользователя: Admin, пароль: 1234)''
== Настройка после установки ==


* доступ к файлу [[API]] "'''/userside/userside3/api.php'''" рекомендуется ограничить на уровне веб-сервера для доступа лишь с разрешённых IP-адресов
=== Конфигурация системных служб ===
После установки необходимо скопировать примеры конфигурационных файлов системных служб и, при необходимости, настроить их (например, указать путь к каталогу userside, если он отличается от /var/www/userside). Выполните команды:
<pre>
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
</pre>


* прописать планировщик UserSide в cron.
=== Установка необходимых зависимостей для usm_poller ===
<pre>
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
</pre>


cat << EOF > /etc/cron.d/userside
=== Запуск супервизора ===
* * * * *  www-data  php /var/www/userside/userside cron > /dev/null 2>&1
Супервизор контролирует работоспособность служб, указанных в его конфигурации. Для запуска супервизора выполните:
EOF
<pre>
sudo systemctl restart supervisor
</pre>
После запуска супервизора, спустя несколько секунд можно понаблюдать за состоянием всех контролируемых им служб. Все службы должны быть в состоянии RUNNING:
<pre>
sudo supervisorctl status
</pre>


* настроить взаимодействие с [[Поддерживаемые биллинги|биллингом]] в соответствии с [[Настройка взаимодействия с биллингом|инструкциями]]
== Сразу после установки ==
На этом установка ERP USERSIDE закончена. Теперь выполните следующие шаги:
* Откройте страницу системы '''<nowiki>http://userside.mydomain.com/</nowiki>''' и выполните вход ''(по умолчанию имя пользователя: Admin, пароль: 1234)''.
* Выполните настройку Websocket в разделе: Настройка - Основная - WebSocket. Включите и впишите имя пользователя и пароль WebStomp пользователя, которого вы создавали ранее в разделе RabbitMQ.
* Выполните основные настройки в разделе: [[Настройка - Основная|Настройка - Основная]].
* Настройте взаимодействие с [[Поддерживаемые биллинги|биллингом]] в соответствии с [[Настройка взаимодействия с биллингом|инструкциями]].
* Ознакомьтесь с инструкциями на странице: [[С чего начать?]].
* Желательно ограничить доступ к файлу [[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]]. Вы всегда можете удалить копию и начать сначала. Это просто и безопасно. Но если вы желаете обновить работающую систему, то выполняйте его в моменты наименьшей нагрузки с запасом по времени, необходимым для аварийного восстановления, если вдруг что-то пойдет не так. Всегда обязательно делайте резервную копию базы данных и файлов перед обновлениями. Если обновление будет прервано, особенно на этапе миграции данных, то есть риск того, что восстановить корректно данные будет очень непросто или даже невозможно. В общем, ответственность за наличие актуальной резервной копии лежит целиком на вас.


'''Крайне рекомендуется после установки системы установить периодическое ''(лучше - ежедневное)'' создание резервной копии штатными средствами PostgeSQL и её хранение НА ДРУГОМ узле.
Возможно перед обновлением вам понадобится обновить PostgreSQL. Обратитесь к нашей инструкции по обновлению PostgreSQL для проведения этой процедуры предже чем начнете процесс обновления ERP USERSIDE.
Например:'''
sudo -u postgres pg_dump --no-acl --no-owner -Fc userside > /backup/userside.dump


Восстановить сделанную таким образом резервную копию можно различными способами. Обратите внимание, что дампы могут быть несовместимы между разными минорными версиями PostgreSQL. По крайней мере разработчики PostgreSQL предостерегают от использования таких дампов. Выполняйте развертывание дампа на сервер с той же минорной версией (например, 11.4), как и у сервера, на котором был получен дамп.
==== Процесс обновления ====
Мы настоятельно рекомендуем выполнять тестовые обновления на [[HOWTO:_Клонирование_USERSIDE|копии системы]].


Перед восстановлением базы данных необходимо обязательно очистить кеш Redis ''(только для версии 3.13 и новее)''
Для проведения обновления запустите инсталлятор в режиме install и следуйте инструкциям:
php userside cache/flush-all
<pre>
cd /var/www/userside
sudo -u www-data php userside_install.phar install
</pre>
 
После обновления USERSIDE нужно обязательно обновить зависимости usm_poller:
<pre>
sudo -H microservice/poller/venv/bin/pip install -U -r microservice/poller/requirements.txt
</pre>
 
Теперь нужно перезапустить все службы, которолируемые супервизором и проследить чтобы все они запустились и были в состоянии RUNNING:
<pre>
sudo supervisorctl restart all
sudo supervisorctl status
</pre>
 
== Обслуживание системы ==
Для поддержания системы в рабочем состоянии и обеспечения надежной ее работы в будущем рекомендуется выполнять несколько простых дейсвтий:
* периодически создавать резервную копию базы данных
* периодически создавать резервную копию загруженных файлов (это можно сделать просто архивируя каталог /var/www/userside/var/attachments и файл .env)
* периодически наблюдать за производительностью сервера (при помощи htop, atop) и брокера RabbitMQ и принимать решения о масштабировании пулов fpm, фоновых процессов ядра и микросервисов
 
=== Резервное копирование ===
Установите периодическое резервное копирование базы данных и пользовательских файлов. Желательно минимум раз в сутки в моменты наименьшей нагрузки на сервер. В PostgreSQL существует два способа создать резервную копию базы данных: dump и sql-script. У каждого из них есть свои преимущества и недостатки. Первый создает безопасный дамп базы данных целиком, а второй создает SQL-скрипт, выполняя который можно восстановить как структуру так и данные. Рекомендуем обратиться к [https://postgrespro.ru/docs/postgresql/13/app-pgdump документации по использованию команды pg_dump] для выбора более подходящего для вас способа или набора параметров.
 
Ниже приведены две команды для создания резервной копии базы данных — выбирайте одну из них и добавляйте в ваш crontab:
<pre>
# DUMP
sudo -u postgres pg_dump --no-acl -Fc userside > /backup/userside.dump


Если необходимо восстановить базу данных из резервной копии в обычном режиме '''с автоматическим созданием базы данных или перезаписью''' (имя базы берется из дампа!), выполните следующую команду. Обратите внимание! Имя базы данных в данном случае обязательно указывается '''postgres''' (имя системной базы данных), а не то, куда вы собираетесь выполнить восстановление - не изменяйте это!
# SQL-script
При выполнении этой команды, база данных будет создана автоматически (вся необходимая информация для этого, включая имя базы данных, находится в резервной копии). Если база данных уже существует - она будет сначала удалена, а затем создана автоматически. Имя базы данных будет взято из дампа!
sudo -u postgres pg_dump --no-acl -Fp -Z 5 userside > /backup/userside.sql.gz
sudo -u postgres pg_restore --clean --if-exists --create --exit-on-error --dbname=postgres /backup/userside.dump
</pre>


Если необходимо восстановить резервную копию в базу данных с ''другим именем'' (отличающимся от имени базы данных, с которой была сделана эта резервная копия), выполните команду, приведенную ниже. В этом случае вместо имени системной БД postgres необходимо '''явно указать имя базы данных''', в которую необходимо восстановить содержимое резервной копии. База данных перед восстановлением '''должна существовать и должна быть пустой'''. Если базе не пустая, рекомендуется ее пересоздать.
Для создания минимальной резервной копии '''файлов''' можно использовать следующую команду (для версии 3.15 и новее):
  sudo -u postgres pg_restore --clean --if-exists --exit-on-error --dbname=userside /backup/userside.dump
  sudo tar -czf /backup/userside.tgz .env common/config/settings.json var/attachments
Выполнив эту команду произойдет восстановление из дампа в базу данных с именем userside (а не с тем именем, которое в дампе).
Этих файлов вместе с базой данных будет достаточно для восстановления работы USERSIDE. Но вы можете выполнять резервное копирование всего каталога /var/www/userside для большей надежности.


Если после восстановления базы данных отсутствуют права на таблицы из схемы public (такое может быть на некоторых отдельных версиях postgresql), назначьте привилегии для схемы public вручную (именно так, не изменяйте эти строки!):
=== Восстановление из резервной копии ===
GRANT ALL ON SCHEMA public TO postgres;
Для восстановления из дампа используется команда pg_restore. [https://postgrespro.ru/docs/postgresql/13/app-pgrestore Документация по использованию pg_restore]. Для восстановления из SQL-скрипта используется утилита psql. [https://postgrespro.ru/docs/postgresql/13/app-psql Документация по использованию psql].
GRANT ALL ON SCHEMA public TO PUBLIC;


Если вам необходимо скопировать существующую базу данных для тестирования новых версий или других целей, то используйте для этого команду создания базы данных:
==== DUMP ====
sudo -u postgres createdb -e --encoding="UTF-8" --locale="ru_RU.UTF-8" --owner=userside --template=userside userside_new
Дамп содержит целиком базу данных со всеми ее элементами. Поэтому перед восстановлением базы данных из дампа её не должно существовать на сервере — удалите базу данных перед восстановлением из дампа. Также важно, чтобы пользователь базы данных (владелец всех элементов) уже существовал — создайте его перед восстановлением, если вы восстанавливаете базу данных на новом сервере, где нужного пользователя еще нет.
В этом случае просто создается новая база данных, в качестве шаблона которой используется существующая база данных. Используйте именно такой способ, если нужно сделать копию базы данных.
Такой способ подходит только если имя владельца новой и текущей базы совпадают.


Если вы планируете восстановить базу данных из резервной копии таким образом, чтобы у новой базы данных был другой владелец (userside_new_user), то вам нужно будет сделать следующее:
Также обратите внимание, что структура дампа может быть несовместима между разными версиями PostgreSQL. Это не обязательно так, но вполне вероятно.
sudo -u postgres createuser userside_new_user -P
sudo -u postgres createdb -e -E "UTF-8" -l "ru_RU.UTF-8" -O userside_new_user -T template0 userside_new_db
sudo -u postgres psql -d userside_new_db -c "CREATE EXTENSION postgis"
sudo -u postgres pg_restore --no-owner --role=userside_new_user --exit-on-error --dbname=userside_new_db /backup/userside.dump
Во время выполнения последней команды вы получите сообщения об ошибках перезаписи объектов postgis внутри базы данных (порядка 5 сообщений), так как при восстановлении была явно указана новая роль, которая не может быть применена к системным объектам postigs. Внимательно просмотрите сообщения об ошибках, чтобы они не относились к каким либо другим объектам базы данных.


'''Рекомендуется ознакомиться с инструкциями на странице: [[С чего начать?]]'''
Для восстановления из дампа используйте команду:
sudo -u postgres pg_restore --clean --if-exists --create --exit-on-error --dbname=postgres /backup/userside.dump
Обратите внимание, что имя базы данных в команде обязательно должно быть '''postgres''', так как имя восстанавливаемой базы данных берется из дампа.


Отдельно стоит отметить резервное копирование прикрепленных файлов в системе. С течением времени объем прикреплённых файлов будет расти и достигать больших величин. Поэтому резервное копирование будет долгим и избыточным, хотя и необходимым. Обдумайте как настроить периодический бэкап файлов из директории /userside/ ''(возможно следует настроить бэкап только обновлённых файлов)''
==== SQL-script ====
Восстановить базу данных из SQL-скрипта можно при помощи команды:
gunzip < /backup/userside.sql.gz | sudo -u postgres psql -d userside
База данных перед выполнением этой команды уже должна существовать, но при этом быть пустой. Также должен существовать пользователь (владелец) объектов базы данных.
 
==== После восстановления базы данных ====
После восстановления базы данных любым способом, необходимо очистить кэш ERP USERSIDE, т.к. в кэше теперь находятся данные, отличные от данных в базе. Перейтите в каталог /var/www/userside и выполните команду очистки кэша:
cd /var/www/userside
php run cache/flush-all
Для версии 3.17 и ниже вместо последней команды:
php userside cache/flush-all


== Копия системы для тестирования или исследований ==
Если версии файлов USERSIDE и дампа базы отличаются, то после восстановления базы данных из бекапа необходимо привести версию USERSIDE к соответствующей данным. Для этого в каталоге /var/www/userside выполните команду:
sudo -u www-data php userside_install.phar repair


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


* скопируйте файлы приложения
По умолчанию в Postgres включена система '''автоматического вакуумирования''', которая работает постоянно параллельно самой СУБД. Автоматическое вакуумирование производит удаление из файлов "мёртвых" кортежей, чтобы высвободившееся место могло быть повторно использовано новыми данными. Но такой режим вакуумирования не выполняет ''дефрагментацию файлов'', оставляя их размер, как минимум, тем же.
cd /var/www/
sudo cp -r userside userside-new


* настройте web-сервер для работы с копией - скопируйте конфигурационный файл, отредактируйте и перечитайте конфигурацию nginx:
В большинстве случаев автоматического вакуумирования вполне достаточно и мы не рекомендуем отключать автовакуум, чтобы ваши файлы не разрослись до огромных размеров, а работа базы не замедлилась в десятки или сотни раз.
sudo cp /etc/nginx/conf.d/userside.conf /etc/nginx/conf.d/userside-new.conf
sudo sed -i "s@/var/www/userside/userside3@/var/www/userside-new/userside3@" "/etc/nginx/conf.d/userside-new.conf"
sudo sed -i "s@/var/log/nginx/userside@/var/log/nginx/userside-new@" "/etc/nginx/conf.d/userside-new.conf"
sudo sed -i "s@старое.доменное.имя@новое.доменное.имя@" "/etc/nginx/conf.d/userside-new.conf"
sudo systemctl reload nginx


* скопируйте базу данных (или создайте новую базу данных и восстановите ее из резервной копии):
Процедура '''полного вакуумирования''', которую можно запустить вручную, производит дефрагментацию, уменьшая размер файлов базы данных. Но она выполняется с полной блокировкой таблиц! Процедуру полного вакуумирования (а также перестроения индексов) желательно выполнять во время наименьшей нагрузки на сервер при явной необходимости (если объем файлов базы данных слишком большой, в десятки или сотни раз превышает обычный объем). Во время этой процедуры таблицы базы данных будут заблокированы, так как эта процедура создает новые файлы с данными и переносит в них только "живые" данные. После этой процедуры также желательно выполнить процедуру перестроения индексов. Подробную информацию по [https://postgrespro.ru/docs/postgresql/13/sql-vacuum вакуумированию] и [https://postgrespro.ru/docs/postgresql/13/sql-reindex реиндексации] вы можете найти в документации PostgreSQL.
sudo -u postgres createdb -e --encoding="UTF-8" --locale="ru_RU.UTF-8" --owner=userside --template=userside userside_new


* В версии 3.13 и новее перейдите в каталог с новой копией, отредактируйте переменные окружения в файле .env таким образом, чтобы они работали с новой базой данных и с другой (свободной) базой данных redis (в основной инсталляции у вас, скорее всего, используется база данных redis под номером 0; вы можете использовать еще 15, имеющихся по умолчанию). За это отвечают переменные:
Ниже приведены команды, которые являются псевдонимами одноимённым SQL-запросам. Если вам проще выполнять SQL-запросы вместо команд, обратитесь к документации по ссылкам выше.
US_URL=http://новое.доменное.имя
US_DB_DSN=pgsql:host=localhost;dbname=userside_new;port=5432
US_REDIS_DB=1


* В версии до 3.13 отредактируйте параметры подключения к БД в файле common/config/db.php и URL в файле userside3/main/config/config.php
sudo -u postgres vacuumdb --full --analyze userside
sudo -u postgres reindexdb userside


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


== Частозадаваемые вопросы (FAQ) ==
=== Мониторинг RabbitMQ ===
''Необходимо только для версии 3.16 и более новой.''


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

Текущая версия от 11:41, 18 октября 2024

en | ru

ВНИМАНИЕ: Данная инструкция актуальна для версий ERP USERSIDE 3.18

Описание

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

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

Требования

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

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

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

3.18

  • PHP: 8.1
  • Расширения PHP: ctype, gd, json, libxml, mbstring, openssl, pdo, pdo_pgsql, posix, simplexml, snmp, sockets, zlib, pcntl
  • Дополнительные расширения PHP: ldap, soap
  • Python: Необходим Python3 любой поддерживаемой на данный момент версии. Статус версий можно посмотреть здесь: "Status of Python versions". Рекомендуется использовать версию с состоянием "security" или "bugfix". Версии отмеченные как "end-of-life" не поддерживаются. Отмеченные как "feature" не рекомендуется использовать.
  • Модули Python: pip, venv
  • PostgreSQL: 10+ (желательно 16)
  • Redis: 5+ (желательно 7)
  • RabbitMQ: 3.8+ (желательно 3.13)
  • Supervisor

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

Каталог, в который устанавливается 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, но вам необходимо будет заменить его на свое. Пропишите это доменное имя в /etc/hosts, если оно отличается от имени хоста, на котором производистя установка.

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

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

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

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

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

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

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

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

Установка

Внимание! Перед установкой PostgreSQL в вашей операционной системе должна быть установлена ваша местная локаль и корректный часовой пояс! Это можно сделать и позже, но будет намного проще, если это будет сделано до установки 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-16 postgresql-16-postgis-3

Настройка

Создайте пользователя и базу данных для ERP USERSIDE. В примере ниже создается пользователь с именем userside и база данных с таким же именем. Если ваша локаль не uk_UA, не забудьте изменить команду. Затем к базе данных подключается расширение 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/16/main/. В файле postgresql.conf необходимо раскомментировать и изменить значение параметра listen_addresses, указав там все IP-адреса интерфейсов сервера, на которых он может принимать подключения к PostgreSQL. В файле pg_hba.conf необходимо в самом конце добавить строку по аналогии с предыдущими, указывающую, с какого адреса может подключаться пользователь ERP USERSIDE. Но если ваш PostgreSQL расположен на том же сервере, что и USERSIDE - нет необходимости вносить какие либо корректировки в эти файлы.

Redis

Стандартный репозиторий Debian 12 включает версию Redis 7.0.15. Эта версия подходит для работы ERP USERSIDE.

Установка

sudo apt install -y redis-server

Настройка

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

openssl rand --hex 32

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

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

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

где вместо MYPASSWORDHERE укажите хэш парольной фразы поулченый ранее.

Также необходимо отключить таймаут (на некоторых версиях 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

Стандартный репозиторий Debian 12 включает старую версию RabbitMQ 3.10. Вы можете использовать ее — она поддерживается. Однако, эта версия относительно старая и лучшим вариантом будет установить новую версию из альтернативных репозиториев. На официальном сайте RabbitMQ находится достаточно подробная информация по установке RabbitMQ для каждой операционной системы.

Добавление альтернативных репозиториев

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

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

Установка

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 (минимальные права на чтение определенных объектов брокера). Но вы можете создать только два: администратора, который также будете использоваться для USERSIDE, и пользователя для websocket. Это обязательно должны быть минимум два разных пользователя, так как пароль для 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_user_tags "userside" "monitoring"
sudo rabbitmqctl set_permissions -p "/" "userside" ".*" ".*" ".*"

Создайте пользователя WebSTOMP. Он понадобится для использования уведомлений через WebSocket. Вместо 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-.*"

Внимание! Имя пользователя и пароль WebSTOMP вам нужно будет указать в настройках в интерфейсе USERSIDE (Меню: Настройки - Основные - Websocket).

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

Перезапустите службу rabbitmq: 

sudo systemctl restart rabbitmq-server

Управление

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

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

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

PHP

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

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 php8.1-{fpm,cli,common,curl,intl,mbstring,opcache,pgsql,readline,xml,zip,snmp,gd}

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

sudo apt install -y php8.1-ldap

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

sudo apt install -y php8.1-soap

Настройка

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

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

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

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

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

Установка

sudo apt install -y nginx

Настройка

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

Следующий пример настройки подразумевает, что 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 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; }
}

Также, возможно, вы захотите настроить 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

Необходим Python3 любой поддерживаемой на данный момент версии. Статус версий можно посмотреть здесь: "Status of Python versions". Рекомендуется использовать версию с состоянием "security" или "bugfix". Версии отмеченные как "end-of-life" не поддерживаются. Отмеченные как "feature" не рекомендуется использовать.

Если у вас на хосте неподдерживаемая версия ("end-of-life"), то нужно обязательно установить дополнительно более свежую версию Python.

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

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

Supervisor

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

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

Конфигурация системных служб

После установки необходимо скопировать примеры конфигурационных файлов системных служб и, при необходимости, настроить их (например, указать путь к каталогу userside, если он отличается от /var/www/userside). Выполните команды: 

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

Установка необходимых зависимостей для 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

Запуск супервизора

Супервизор контролирует работоспособность служб, указанных в его конфигурации. Для запуска супервизора выполните: 

sudo systemctl restart supervisor

После запуска супервизора, спустя несколько секунд можно понаблюдать за состоянием всех контролируемых им служб. Все службы должны быть в состоянии RUNNING: 

sudo supervisorctl status

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

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

  • Откройте страницу системы http://userside.mydomain.com/ и выполните вход (по умолчанию имя пользователя: Admin, пароль: 1234).
  • Выполните настройку Websocket в разделе: Настройка - Основная - WebSocket. Включите и впишите имя пользователя и пароль WebStomp пользователя, которого вы создавали ранее в разделе RabbitMQ.
  • Выполните основные настройки в разделе: Настройка - Основная.
  • Настройте взаимодействие с биллингом в соответствии с инструкциями.
  • Ознакомьтесь с инструкциями на странице: С чего начать?.
  • Желательно ограничить доступ к файлу 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.

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

Мы настоятельно рекомендуем выполнять тестовые обновления на копии системы.

Для проведения обновления запустите инсталлятор в режиме install и следуйте инструкциям: 

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

После обновления USERSIDE нужно обязательно обновить зависимости usm_poller: 

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

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

sudo supervisorctl restart all
sudo supervisorctl status

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

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

  • периодически создавать резервную копию базы данных
  • периодически создавать резервную копию загруженных файлов (это можно сделать просто архивируя каталог /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 run cache/flush-all

Для версии 3.17 и ниже вместо последней команды: 

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, а затем перезапустите супервизор.

Источник — https://wiki.userside.eu/index.php?title=Установка_для_версии_3.18&oldid=19914