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

Материал из WiKi - UserSide
Нет описания правки
Строка 1: Строка 1:
'''ВНИМАНИЕ: Данная инструкция актуальна для версий ERP "UserSide" 3.11 и выше. Для версии ниже 3.11 - используйте отдельную инструкцию по [[Установка для версии 3.10 и более ранних|установке для 3.10]].
'''ВНИМАНИЕ: Данная инструкция актуальна для версий ERP USERSIDE 3.11 и выше. Для версий 3.10 и ниже - используйте отдельную инструкцию по [[Установка для версии 3.10 и более ранних|установке для 3.10]].


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


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


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


* установите 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):
Также обратите внимание, что ваша операционная система должна быть сконфигурирована с корреткным часовым поясом и локалью. От этого зависит правильность отображения информации и корректность сортировки.


Список требуемых расширений PHP содержит все расширения, не входящие в состав ядра PHP. Часть из этих расширений может поставляться вместе с основным пакетом PHP либо в составе пакета php-common, другая же часть должна быть установлена дополнительно.
=== 3.16 (в стадии разработки) ===
* 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 - <code>/var/www/userside</code>. Внутри этого каталога должен быть подкаталог 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 update
  sudo apt install -y apt-transport-https lsb-release ca-certificates
  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)/updates 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 -
  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
  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
Если у вас другая операционная система, вы можете найти необходимые команды для нее на [https://www.postgresql.org/download/ официальном сайте PostgreSQL].
''Шаг с добавлением альтернативного репозитория здесь и далее необязательный, но только при условии, что в основном репозитории вашей операционной системы находятся пакеты тех версий, которые попадают в диапазон требуемых для устанавливаемой версии ERP USERSIDE.''
==== Установка ====
sudo apt install -y postgresql-13 postgresql-13-postgis-3
==== Настройка ====
Создайте пользователя (роль) и базу данных для ERP USERSIDE. В примере ниже создается пользователь с именем userside и база данных с таким же именем. Затем к базе данных подключается расширение PostGis, необходимое для манипуляции над геометрическими данными. После выполнения первой строки, вам необходимо будет дважды ввести пароль для нового пользователя - запишите этот пароль, он понадобится вам далее для установки ERP USERSIDE
sudo -u postgres createuser userside -P
sudo -u postgres createdb -e -E "UTF-8" -l "ru_RU.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/13/main/. В файле postgresql.conf необходимо раскомментировать и изменить значение параметра listen_addresses, указав там все IP-адреса интерфейсов сервера, на которых он может принимать подключения к PostgreSQL. В файле pg_hba.conf необходимо в самом конце добавить строку по аналогии с предыдущими, указывающую, с какого адреса может подключаться пользователь ERP USERSIDE. Но если ваш PostgreSQL расположен на том же сервере, что и PHP и всё остальное - нет необходимости вносить какие либо корректировки в этот файл.
==== Тонкая настройка сервера PostgreSQL ====
Для максимальной производительности необходимо настроить PostgreSQL под особенности вашего сервера. Это позволяет многократно увеличить производительность базы данных и значительно ускорить работу. Обязательно выполните эту настройку. В этом вам помогут специальные онлайн калькуляторы и дополнительная информация:
* https://pgtune.leopard.in.ua/
* http://pgconfigurator.cybertec.at/
* https://wiki.postgresql.org/wiki/Performance_Optimization
* https://ruhighload.com/post/%D0%A2%D1%8E%D0%BD%D0%B8%D0%BD%D0%B3+%D0%B1%D0%B0%D0%B7%D1%8B+Postgres
Всё, что вам нужно сделать - ввести в калькулятор данные вашего сервера и получить рекомендуемые параметры конфигурации, которые вы внесете в файл /etc/postgresql/13/main/postgresql.conf
=== Redis ===
==== Альтернативный способ установки ====
Стандартный репозиторий Debian 10 включает версию Redis 5.0.3, выпущенную в декабре 2018 года. Эта версия подходит для работы ERP USERSIDE. Если вы хотите установить последнюю версию из 6-й ветки, вам придется собрать Redis вручную. Если у вас нет опыта в этом, то просто установите Redis как показано ниже - этого вполне достаточно. Если вы используете Ubuntu server, то можете воспользоваться официальным PPA-репозиторием.
Информацию о ручной сборке Redis и о PPA-репозитории вы можете найти на [https://redis.io/download официальном сайте 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 и убедитесь, что он работает (в ответ должны получить 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. Поэтому добавление альтернативных репозиториев является обязательным в этом случае. На [https://www.rabbitmq.com/download.html официальном сайте RabbitMQ] находится достаточно подробная информация по установке RabbitMQ для каждой операционной системы.
==== Установка ====
sudo apt-key adv --keyserver "hkps://keys.openpgp.org" --recv-keys "0x0A9AF2115F4687BD29803A206B73A36E6026DFCA"
curl -1sLf https://dl.cloudsmith.io/public/rabbitmq/rabbitmq-erlang/gpg.E495BB49CC4BBE5B.key | sudo apt-key add -
curl -1sLf https://dl.cloudsmith.io/public/rabbitmq/rabbitmq-server/gpg.9F4587F226208342.key | sudo apt-key add -
Следующий блок скопируйте и вставьте целиком в командную строку
sudo tee /etc/apt/sources.list.d/rabbitmq.list << EOF
deb https://dl.cloudsmith.io/public/rabbitmq/rabbitmq-erlang/deb/ubuntu bionic main
deb-src https://dl.cloudsmith.io/public/rabbitmq/rabbitmq-erlang/deb/ubuntu bionic main
deb https://dl.cloudsmith.io/public/rabbitmq/rabbitmq-server/deb/ubuntu bionic main
deb-src 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
sudo rabbitmq-plugins enable rabbitmq_web_stomp
==== Настройка ====
Скопируйте и вставьте целиком следующий блок:
sudo tee /etc/rabbitmq/rabbitmq.conf << EOF
listeners.tcp.default = 5672
web_stomp.port = 15674
web_stomp.cowboy_opts.max_keepalive = 60
EOF
Теперь создайте пользователя для администрирования RabbitMQ. В данном примере используется имя пользователя '''admin''' и пароль '''password'''. Пользователю сразу после создания присваивается тэг <code>administrator</code>, наделяющий пользователя максимальными правами администратора и затем устанавливаются разрешения для vhost <code>/</code> позволяющие полный доступ к конфигурированию, записи и чтению всего в пределах этого 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:
sudo rabbitmqctl add_user "userside-stomp" "userside-stomp-password"
sudo rabbitmqctl set_permissions -p "/" "userside-stomp" "^userside-stomp:id-.*" "" "^userside-stomp:id-.*"
''* vhost - это виртуальный хост внутри RabbitMQ, позволяющий разграничить различные варианты использования одного и того же сервера разными приложениями. Как, например, разные базы данных на одном сервере СУБД. vhost по умолчанию имеет имя / и почти всегда вам этого достаточно. Но если вы планируете, например, запустить несколько копий ERP USERSIDE на одном сервере, то для каждой копии вам нужно будет создать свой vhost и, соответственно, пользователей для него. Подробней обратитесь к [https://www.rabbitmq.com/vhosts.html официальному руководству].''
==== Управление ====
Одна из команд, приведенных выше, устанавливает в RabbitMQ модуль управления, предоставляющий удобный WEB-интерфейс для мониторинга, диагностики и управления сервером RabbitMQ. При помощи этого модуля можно осуществлять мониторинг сервера, следить за количеством сообщений в очередях и другими состояниями. Всё это можно делать и используя консольную утилиту <code>rabbitmqctl</code>, но использование WEB-интерфейса может быть значительно наглядней и удобней. Если вам не нужен WEB-интерфейс для управления сервером, можете отказаться от установки модуля '''rabbitmq_management''' на этапе установки.
По умолчанию WEB-интерфейс управления доступен по адресу http://rabbit-server-name:15672
Подробнее о модуле управления можно [https://www.rabbitmq.com/management.html прочитать на официальном сайте RabbitMQ].
=== PHP ===
==== Альтернативный репозиторий ====
Если ваша операционная система в своем стандартном репозитории пакетов имеет необходимую версию PHP, то можно установить PHP и расширения напрямую из основного репозитория операционной системы. Например, версия Debian-10 (Buster) в своем стандартном дистрибутиве содержит PHP версии 7.3, который вполне подходит для ERP USERSIDE 3.16 и, скорее всего, подойдет и для 3.17 тоже. Однако, если версия вашей операционной системы более старая, то нужных версий пакетов там может просто не оказаться. В таком случае можно добавить в вашу операционную систему альтернативный репозиторий. Выполните команды, приведенные ниже:
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 install -y php7.4-fpm php7.4-cli php7.4-common php7.4-curl php7.4-intl php7.4-json php7.4-mbstring php7.4-opcache php7.4-pgsql php7.4-readline php7.4-xml php7.4-zip php7.4-snmp php7.4-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
=== NGINX ===
==== Альтернативный официальный репозиторий ====
Чтобы иметь возможность всегда устанавливать и обновляться до последней версии PostgreSQL, добавьте в вашу операционную систему альтернативный официальный репозиторий, выполнив команды:
  wget --quiet -O - http://nginx.org/keys/nginx_signing.key | sudo apt-key add -
  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 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
  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"
Если у вас другая операционная система, вы можете найти необходимые команды для нее на официальном сайте NGINX: https://docs.nginx.com/nginx/admin-guide/installing-nginx/installing-nginx-open-source/
  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 apt-get remove -y nginx-common apache2
sudo sed -i "s@upload_max_filesize = 2M@upload_max_filesize = 50M@" "/etc/php/7.2/fpm/php.ini"
  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"
  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'''.
Следующий пример настройки подразумевает, что ERP USERSIDE будет установлен в стандартный каталог системы <code>/var/www/userside</code>. Если вы желаете установить ERP USERSIDE в другой каталог, пожалуйста, не забывайте исправлять его во всех последующих примерах. Чтобы не ошибиться, мы рекомендуем использовать именно каталог <code>/var/www/userside</code>.


  sudo mkdir -p /var/www/userside/userside3
В этом каталоге будет располагаться web-root, то есть файлы, доступные через протокол http.
 
* создайте сайт для nginx (или отредактируйте имеющийся сайт по умолчанию). Для этого создайте файл /etc/nginx/conf.d/userside.conf и поместите в него текст:


Скопируйте целиком весь блок ниже и вставьте в командную строку - это изменит файл настроек сервера nginx default.conf:
sudo tee /etc/nginx/conf.d/default.conf << EOL
  server {
  server {
     listen               80;
     listen       80;
     server_name         userside.mycompany.com; # ИЗМЕНИТЕ ЭТО ИМЯ
     server_name userside.mycompany.com;
     charset             utf-8;
     charset     utf-8;
     client_max_body_size 50M;
     client_max_body_size 50M;
     access_log  /var/log/nginx/userside-access.log;
     access_log  /var/log/nginx/userside-access.log;
Строка 55: Строка 273:
     location = /robots.txt  { access_log off; log_not_found off; }
     location = /robots.txt  { access_log off; log_not_found off; }
     location / {
     location / {
         try_files $uri $uri/ =404;
         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)$ {
     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)$ {
Строка 65: Строка 283:
     }
     }
     location ~ \.php$ {
     location ~ \.php$ {
         try_files    $uri =404;
         try_files    \$uri =404;
         fastcgi_split_path_info ^(.+\.php)(/.+)$;
         fastcgi_split_path_info ^(.+\.php)(/.+)$;
         fastcgi_pass  unix:/run/php/php7.2-fpm.sock;
         fastcgi_pass  unix:/run/php/php7.4-fpm.sock;
         fastcgi_index index.php;
         fastcgi_index index.php;
         fastcgi_param SCRIPT_FILENAME $document_root$fastcgi_script_name;
         fastcgi_param SCRIPT_FILENAME \$document_root\$fastcgi_script_name;
         fastcgi_read_timeout 600;
         fastcgi_read_timeout 600;
         include      fastcgi_params;
         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; }
     location ~ /\.ht { deny  all; }
Строка 82: Строка 307:
     }
     }
  }
  }
EOL


* выполните [[Установка PostgreSQL|установку и/или настройку PostgreSQL и расширения Postgis]]
Далее вы должны отредактировать этот файл, например, используя утилиту nano:
 
  sudo nano /etc/nginx/conf.d/default.conf
* выполните [[Установка Redis|установку и/или настройку Redis]]
 
* перезапустите стек
 
sudo systemctl restart postgresql.service
sudo systemctl restart nginx.service
sudo systemctl restart php7.2-fpm.service
 
=== Оптимизация пула PHP-FPM ===
 
PostgreSQL и PHP-FPM поставляются с базовой конфигурацией, позволяющей без проблем запускать эти сервисы на самом слабом оборудовании. Поэтому настройка (тюнинг) конфигурации как минимум этих двух служб является крайне желательной процедурой, позволяющей утилизировать все аппаратные ресурсы сервера и значительно повысить производительность системы.
 
Сперва обязательно проведите оптимизацию PostgreSQL. Как это сделать - указано в [[Установка PostgreSQL#Тонкая настройка|соответствующем разделе]].
 
Далее, после того как оптимизация PostgreSQL выполнена, перейдите к оптимизации пула PHP-FPM. По умолчанию за настройку пула отвечает файл /etc/php/7.2/fpm/pool.d/www.conf
 
Этот файл содержит несколько настроек менеджера процессов (PM), которые начинаются с <code>pm</code>
 
Мы рекомендуем использовать динамический пул, так как на одном сервере работают и другие службы. В этом случае менеджер процессов будет управлять количеством процессов php-fpm в памяти автоматически, высвобождая ресурсы, если в них нет необходимости. По умолчанию менеджер процессов работает именно в этом режиме, но на всякий случай убедитесь, что это именно так: <code>pm = dynamic</code>
 
Далее необходимо настроить количество процессов php-fpm, а также остальные настройки. Здесь понадобится произвести некоторые вычисления.
 
Один процесс php-fpm занимает примерно 48 Мб в ОЗУ (это справедливо только для USERSIDE). Однако, если у вас слишком большой объем данных в USERSIDE, то это значение может быть несколько больше. Главное использовать не максимальное, а среднее значение. Ведь не все до единого запросы потребляют максимальное количество ОЗУ. Чтобы узнать, какое количество ОЗУ потребляют ваши процессы PHP-FPM, то в момент нормальной рабочей нагрузки на WEB-приложение USERSIDE, выполните команду:
 
  ps -eo rss,comm,cmd | grep php-fpm
 
В результате вы получите вывод, состоящий из трех колонок:
 
  3304 php-fpm7.2      php-fpm: master process (/etc/php/7.2/fpm/php-fpm.conf)
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 Мб. Запоминаем это значение.
 
Теперь необходимо узнать, сколько свободной оперативной памяти у нас есть. Делать это необходимо после оптимизации PostgreSQL и желательно в момент нормальной рабочей нагрузки. Выполните:
 
free -m
 
В результате вы получите приблизительно следующий вывод:
 
              total        used        free      shared  buff/cache  available
Mem:            996        147        331        124        516        581
 
Чтобы вычислить объем оперативной памяти, который можно использовать, воспользуемся формулой: available = total - (used + buff). В данном случае это 333 Мб.
 
Весь этот объем оперативной памяти мы бы могли использовать для пула php-fpm. Но все же желательно взять от него около 80%, не более. В данном случае это примерно 266 Мб.
 
Теперь считаем количество воркеров. Один воркер потребляет в среднем 38 Мб, а объем свободной памяти 266 Мб. Всё это очень приблизительно, так как эти значения далеко не постоянны. Нам остается просто разделить объем свободной памяти на количество памяти, потребляемой одним воркером. Получим 266 / 38 = 7. Такое максимальное количество воркеров мы можем запустить.
 
Указываем в качестве значения <code>pm.max_children = 7</code>.
 
Далее необходимо настроить минимальное и максимальное количество воркеров, ожидающих соединеия. За это отвечают параметры <code>pm.min_spare_servers</code> и <code>pm.max_spare_servers</code> соответственно. Значения этих параметров подбираются "на глаз" и зависят от реального количества запросов, от их "тяжести" и многого другого. Для начала возьмем минимальное количество ожидающих воркеров примерно 25% от общего максимума (max_children), а максимальное примерно 50%.
 
pm.min_spare_servers = 2
pm.max_spare_servers = 4
 
Далее необходимо настроить количество воркеров, которое будет запущено при старте пула php-fpm. За это отвечает параметр <code>pm.start_servers</code> и его значение рассчитывается по формуле: min_spare_servers + (max_spare_servers - min_spare_servers) / 2. В нашем случае, это 3


Итого, настройка менеджера процессов пула PHP-FPM будет следующей:
Вместо userside.mycompany.com укажите ваше доменное имя, выделенное для ERP USERSIDE. Также, возможно, вы захотите настроить SSL и что-либо еще. Эта тема выходит за рамки данной инстуркции.


pm.max_children = 7
Проверьте конфигурацию и если она в порядке перезагрузите nginx:
pm.min_spare_servers = 2
  sudo nginx -t && sudo systemctl restart nginx
pm.max_spare_servers = 4
  pm.start_servers = 3


Здесь важно отметить следующие моменты. В этих демонстрационных расчетах использовались данные сервера с объемом ОЗУ 1 Гб. В вашем же случае на реальном сервере максимальное количество воркеров может получиться очень большим - несколько сотен. Однако не стоит использовать такое большое количество воркеров, если у вас работает всего два оператора и никто больше не работает с USERSIDE. Лишние воркеры будут просто бесполезно занимать ОЗУ, которое могло быть использовано тем же PostgreSQL в мирных целях. Данные рекомендации помогут понять, какое максимальное количество воркеров можно использовать для максимальной утилизации системы, но если в таком количестве процессов, ожидающих http-запросы, нет смысла, то нет необходимости использовать его - просто понизьте его до разумных значений.
=== Python ===
Debian 10 в стандартном репозитории содержит Python 3.7. Это минимальная поддерживаемая версия, поэтому можно обойтись без альтернативных репозиториев или ручной сборки из исходных кодов.


Также рекомендуем наблюдать за файлом журнала php-fpm на предмет проблем с воркерами.
==== Установка ====
sudo apt install -y python3 python3-pip
sudo -H python3 -m pip install --upgrade pip virtualenv


tail -f /var/log/php7.2-fpm.log
=== Supervisor ===
''Необходимо только для версии 3.16 и более новой.''


Об этом могут говорить строки вроде следующей:
==== Установка ====
 
  sudo apt install -y supervisor
  WARNING: [pool www] server reached pm.max_children setting (5), consider raising it


== Загрузка и запуск инсталлятора ==
== Загрузка и запуск инсталлятора ==
Строка 165: Строка 334:
См. также: [[Инсталлятор|Справку по инсталлятору]]
См. также: [[Инсталлятор|Справку по инсталлятору]]


1) перейти в каталог системы
1. перейти в каталог системы
 
  cd /var/www/userside
  cd /var/www/userside


2) запустить команду
2. загрузить скрипт-инсталлятор
 
  sudo -u www-data php -r "copy('https://my.userside.eu/install', 'userside_install.phar');"  
  php -r "copy('https://my.userside.eu/install', 'userside_install.phar');"  
 
3) запустить инсталлятор от имени пользователя, под которым работает web-сервер (www-data, но может быть и другим)


3. запустить инсталлятор
  sudo -u www-data php userside_install.phar install
  sudo -u www-data php userside_install.phar install


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


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


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


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


Если работа инсталлятора будет прервана по какой-то причине (возникла ошибка миграции данных или другая), то следует запустить инсталлятор с командой repair
sudo chown -R www-data:www-data /var/www/userside
sudo chmod -R u=rwX,g=rwX,o=r /var/www/userside


sudo -u www-data php userside_install.phar repair
== Настройка после установки ==


Если проблему не удается решить самостоятельно - подайте тикет в [[Регламент технической поддержки|техническую поддержку]]
=== Планировщик ===
Скопируйте и вставьте в командную строку следущие строки, чтобы добавить запуск планировщика в системном CRON:
sudo tee /etc/cron.d/userside << EOL
* * * * *  www-data  /usr/bin/php /var/www/userside/userside cron > /dev/null
EOL


По окончанию работы инсталлятора будет выведено сообщение об успешной установке.
=== Фоновые процессы ядра ===
''Необходимо только для версии 3.16 и более новой.''


Если вы произвели установку не от имени пользователя веб-сервера, то обязательно после окончания установки сделайте его владельцем всех файлов userside рекурсивно!
Фоновые процесс ядра находятся в постоянном ожидании сообщений от брокера 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


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


* доступ к файлу [[API]] "'''/userside/userside3/api.php'''" рекомендуется ограничить на уровне веб-сервера для доступа лишь с разрешённых IP-адресов
Управление супервизором происходит при помощи утилиты supervisorctl. Например, чтобы вывести список всех процессов, запущенных и контролируемых супервизором, можно выполнить команду:
sudo supervisorctl status


* прописать планировщик UserSide в cron.
Чтобы перезапустить воркеры ядра (us-core-worker), можно выполнить команду:
sudo supervisorctl restart us-core-worker:*


cat << EOF > /etc/cron.d/userside
Более подробно о командах и способе использования супервизора можно [http://supervisord.org/running.html#running-supervisorctl прочитать в официальной документации].
* * * * *  www-data  php /var/www/userside/userside cron > /dev/null 2>&1
EOF


* настроить взаимодействие с [[Поддерживаемые биллинги|биллингом]] в соответствии с [[Настройка взаимодействия с биллингом|инструкциями]]
=== Фоновые процессы микросервиса поллера ===
''Необходимо только для версии 3.16 и более новой.''


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


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


'''Крайне рекомендуется после установки системы установить периодическое ''(лучше - ежедневное)'' создание резервной копии штатными средствами PostgeSQL и её хранение НА ДРУГОМ узле.
Выполните следующие команды, чтобы настроить виртуальное окружение:
Например:'''
cd /var/www/userside/microservice/poller
  sudo -u postgres pg_dump --no-acl -Fc userside > /backup/userside.dump
  sudo -H python3 -m virtualenv -p /usr/bin/python3 venv
sudo -H ./venv/bin/pip install --upgrade -r requirements.txt


Восстановить сделанную таким образом резервную копию можно различными способами. Обратите внимание, что дампы могут быть несовместимы между разными минорными версиями PostgreSQL. По крайней мере разработчики PostgreSQL предостерегают от использования таких дампов. Выполняйте развертывание дампа на сервер с той же минорной версией (например, 11.4), как и у сервера, на котором был получен дамп. Перед тем, как перенести базу данных на новый сервер, всегда сначала обновляйте PostgreSQL на текущем сервере до версии, которая будет использоваться на новом сервере, и только после этого делайте дамп.
==== Настройка ====
В составе поллера поставляется пример файла настроек супервизора. Скопируйте его как рабочий файл.
sudo cp etc/us-poller-microservice.conf-example /etc/supervisor/conf.d/us-poller-microservice.conf


Перед восстановлением базы данных необходимо обязательно очистить кеш Redis ''(только для версии 3.13 и новее)''
Перезапустите супервизор
  php userside cache/flush-all
  sudo systemctl restart supervisor


Если необходимо восстановить базу данных из резервной копии в обычном режиме '''с автоматическим созданием базы данных или перезаписью''' (имя базы берется из дампа!), выполните следующую команду. Обратите внимание! Имя базы данных в данном случае обязательно указывается '''postgres''' (имя системной базы данных), а не то, куда вы собираетесь выполнить восстановление - не изменяйте это! Также обратите внимание, что пользователь (роль), которому принадлежит база данных и все ее внутренние элементы, также должен существовать до восстановления дампа.
Проверьте, что всё запустилось корректно
При выполнении этой команды, база данных будет создана автоматически (вся необходимая информация для этого, включая имя базы данных, находится в резервной копии). Если база данных уже существует - она будет сначала удалена, а затем создана автоматически. Имя базы данных будет взято из дампа!
  sudo supervisorctl status
  sudo -u postgres pg_restore --clean --if-exists --create --exit-on-error --dbname=postgres /backup/userside.dump


Если необходимо восстановить резервную копию в базу данных с ''другим именем'' (отличающимся от имени базы данных, с которой была сделана эта резервная копия), выполните команду, приведенную ниже. В этом случае вместо имени системной БД postgres необходимо '''явно указать имя базы данных''', в которую необходимо восстановить содержимое резервной копии. База данных перед восстановлением '''должна существовать и должна быть пустой'''. Если базе не пустая, рекомендуется ее пересоздать.
Если возникли проблемы с запуском, попытайтесь запустить микросервис поллера вручную и проанализировать вывод
  sudo -u postgres pg_restore --clean --if-exists --exit-on-error --dbname=userside /backup/userside.dump
  sudo /var/www/userside/microservice/poller/venv/bin/python3 /var/www/userside/microservice/poller/worker.py
Выполнив эту команду произойдет восстановление из дампа в базу данных с именем userside (а не с тем именем, которое в дампе).


Если после восстановления базы данных отсутствуют права на таблицы из схемы public (такое может быть на некоторых отдельных версиях postgresql), назначьте привилегии для схемы public вручную (именно так, не изменяйте эти строки!):
== Сразу после установки ==
GRANT ALL ON SCHEMA public TO postgres;
На этом установка ERP USERSIDE закончена. Теперь вы можете выполнить следующие шаги:
GRANT ALL ON SCHEMA public TO PUBLIC;
* Откройте страницу системы '''<nowiki>http://userside.mydomain.com/oper/</nowiki>''' и выполните вход ''(по умолчанию имя пользователя: Admin, пароль: 1234)''.
* Выполните основные настройки в разделе: [[Настройка - Основная|Настройка - Основная]].
* Настройте взаимодействие с [[Поддерживаемые биллинги|биллингом]] в соответствии с [[Настройка взаимодействия с биллингом|инструкциями]].
* Ознакомьтесь с инструкциями на странице: [[С чего начать?]].
* Желательно ограничить доступ к файлу [[API]] "'''/var/www/userside/userside3/api.php'''" с определенных IP-адресов.


Если вам необходимо скопировать существующую базу данных для тестирования новых версий или других целей, то используйте для этого команду создания базы данных:
== Обновление системы ==
sudo -u postgres createdb -e --encoding="UTF-8" --locale="ru_RU.UTF-8" --owner=userside --template=userside userside_new
Технически возможно любое сквозное обновление, начиная с версии 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.


Если вы планируете восстановить базу данных из резервной копии таким образом, чтобы у новой базы данных был другой владелец (userside_new_user), то вам нужно будет сделать следующее:
Мы рекомендуем сделать копию системы для безопасного проведения обновления. Вы всегда можете удалить копию и начать сначала. Это просто и безопасно. Но если вы желаете обновить работающую систему, то выполняйте его в моменты наименьшей нагрузки с запасом по времени, необходимым для аварийного восстановления, если вдруг что-то пойдет не так. Всегда обязательно делайте резервную копию базы данных и файлов перед обновлениями. Если обновление будет прервано, особенно на этапе миграции данных, то есть риск того, что восстановить корректно данные будет очень непросто или даже невозможно. В общем, ответственность за наличие актуальной резервной копии лежит целиком на вас.
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. Внимательно просмотрите сообщения об ошибках, чтобы они не относились к каким либо другим объектам базы данных.


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


Отдельно стоит отметить резервное копирование прикрепленных файлов в системе. С течением времени объем прикреплённых файлов будет расти и достигать больших величин. Поэтому резервное копирование будет долгим и избыточным, хотя и необходимым. Обдумайте как настроить периодический бэкап файлов из директории /userside/ ''(возможно следует настроить бэкап только обновлённых файлов)''
==== Процесс обновления ====
После создания копии системы или, как минимум, полной резервной копии рабочей системы, если вы не хотите делать клон, вам достаточно запустить команду инсталляции:
cd /var/www/userside-new
sudo -u www-data php userside_install.phar install


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


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


* скопируйте файлы приложения
=== Резервное копирование ===
cd /var/www/
Установите периодическое резервное копирование базы данных. Желательно минимум раз в сутки в моменты наименьшей нагрузки на сервер. В PostgreSQL существует два способа создать резервную копию: dump и sql-script. У каждого из них есть свои преимущества и недостатки. Первый создает безопасный дамп базы данных целиком, а второй создает SQL-скрипт, выполняя который можно восстановить как структуру так и данные. Рекомендуем обратиться к [https://postgrespro.ru/docs/postgresql/13/app-pgdump документации по использованию команды pg_dump] для выбора более подходящего для вас способа или набора параметров.
sudo cp -r userside userside-new


* настройте web-сервер для работы с копией - скопируйте конфигурационный файл, отредактируйте и перечитайте конфигурацию nginx:
Ниже приведены две команды — выбирайте одну из них и добавляйте в ваш crontab:
  sudo cp /etc/nginx/conf.d/userside.conf /etc/nginx/conf.d/userside-new.conf
  # DUMP
  sudo sed -i "s@/var/www/userside/userside3@/var/www/userside-new/userside3@" "/etc/nginx/conf.d/userside-new.conf"
  sudo -u postgres pg_dump --no-acl -Fc userside > /backup/userside.dump
  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"
# SQL-script
sudo systemctl reload nginx
  sudo -u postgres pg_dump --no-acl -Fp -Z 5 userside > /backup/userside.sql.gz


* скопируйте базу данных (или создайте новую базу данных и восстановите ее из резервной копии):
=== Восстановление из резервной копии ===
sudo -u postgres createdb -e --encoding="UTF-8" --locale="ru_RU.UTF-8" --owner=userside --template=userside userside_new
Для восстановления из дампа используется команда pg_restore. [https://postgrespro.ru/docs/postgresql/13/app-pgrestore Документация по использованию pg_restore]. Для восстановления из SQL-скрипта используется утилита psql. [https://postgrespro.ru/docs/postgresql/13/app-psql Документация по использованию psql].
если вы копируете базу данных на другой сервер, перед восстановлением вам нужно будет создать роль, обязательно такую же, как в дампе:
sudo -u postgres createuser userside -P


* В версии 3.13 и новее перейдите в каталог с новой копией, отредактируйте переменные окружения в файле .env таким образом, чтобы они работали с новой базой данных и с другой (свободной) базой данных redis (в основной инсталляции у вас, скорее всего, используется база данных redis под номером 0; вы можете использовать еще 15, имеющихся по умолчанию). За это отвечают переменные:
==== DUMP ====
  US_URL=http://новое.доменное.имя
Если вы используете дамп, то обратите внимание, что структура дампа может быть несовместима между разными версиями PostgreSQL. Это не обязательно так, но выполне вероятно. Для восстановления из дампа используйте команду:
US_DB_DSN=pgsql:host=localhost;dbname=userside_new;port=5432
  sudo -u postgres pg_restore --clean --if-exists --create --exit-on-error --dbname=postgres /backup/userside.dump
US_REDIS_DB=1
Обратите внимание, что имя базы данных в команде обязательно должно быть '''postgres''', так как имя восстанавливаемой базы данных берется из дампа. Перед восстановлением дампа пользователь (владелец элементов базы данных) обязательно должен существовать. Создайте его, если он не существует перед выполнением команды восстановления.


* В версии до 3.13 отредактируйте параметры подключения к БД в файле common/config/db.php и URL в файле userside3/main/config/config.php
==== 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


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

Версия от 15:23, 6 мая 2021

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

Описание

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

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

Требования

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

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

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

3.16 (в стадии разработки)

  • 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)/updates 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.

Установка

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

Настройка

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

sudo -u postgres createuser userside -P
sudo -u postgres createdb -e -E "UTF-8" -l "ru_RU.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/13/main/. В файле postgresql.conf необходимо раскомментировать и изменить значение параметра listen_addresses, указав там все IP-адреса интерфейсов сервера, на которых он может принимать подключения к PostgreSQL. В файле pg_hba.conf необходимо в самом конце добавить строку по аналогии с предыдущими, указывающую, с какого адреса может подключаться пользователь ERP USERSIDE. Но если ваш PostgreSQL расположен на том же сервере, что и PHP и всё остальное - нет необходимости вносить какие либо корректировки в этот файл.

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

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

Всё, что вам нужно сделать - ввести в калькулятор данные вашего сервера и получить рекомендуемые параметры конфигурации, которые вы внесете в файл /etc/postgresql/13/main/postgresql.conf

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

Установка

sudo apt-key adv --keyserver "hkps://keys.openpgp.org" --recv-keys "0x0A9AF2115F4687BD29803A206B73A36E6026DFCA"
curl -1sLf https://dl.cloudsmith.io/public/rabbitmq/rabbitmq-erlang/gpg.E495BB49CC4BBE5B.key | sudo apt-key add -
curl -1sLf https://dl.cloudsmith.io/public/rabbitmq/rabbitmq-server/gpg.9F4587F226208342.key | sudo apt-key add -

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

sudo tee /etc/apt/sources.list.d/rabbitmq.list << EOF
deb https://dl.cloudsmith.io/public/rabbitmq/rabbitmq-erlang/deb/ubuntu bionic main
deb-src https://dl.cloudsmith.io/public/rabbitmq/rabbitmq-erlang/deb/ubuntu bionic main
deb https://dl.cloudsmith.io/public/rabbitmq/rabbitmq-server/deb/ubuntu bionic main
deb-src 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
sudo rabbitmq-plugins enable rabbitmq_web_stomp

Настройка

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

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

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

Теперь создайте пользователя для администрирования 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:

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

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

Управление

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

По умолчанию WEB-интерфейс управления доступен по адресу http://rabbit-server-name:15672

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

PHP

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

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

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 install -y php7.4-fpm php7.4-cli php7.4-common php7.4-curl php7.4-intl php7.4-json php7.4-mbstring php7.4-opcache php7.4-pgsql php7.4-readline php7.4-xml php7.4-zip php7.4-snmp php7.4-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

NGINX

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

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

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

Если у вас другая операционная система, вы можете найти необходимые команды для нее на официальном сайте 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.

Скопируйте целиком весь блок ниже и вставьте в командную строку - это изменит файл настроек сервера nginx default.conf:

sudo tee /etc/nginx/conf.d/default.conf << EOL
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;
    }
}
EOL

Далее вы должны отредактировать этот файл, например, используя утилиту nano:

sudo nano /etc/nginx/conf.d/default.conf

Вместо userside.mycompany.com укажите ваше доменное имя, выделенное для ERP USERSIDE. Также, возможно, вы захотите настроить SSL и что-либо еще. Эта тема выходит за рамки данной инстуркции.

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

sudo nginx -t && sudo systemctl restart nginx

Python

Debian 10 в стандартном репозитории содержит Python 3.7. Это минимальная поддерживаемая версия, поэтому можно обойтись без альтернативных репозиториев или ручной сборки из исходных кодов.

Установка

sudo apt install -y python3 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.

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

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

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

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

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

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

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

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

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

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

Для восстановления из дампа используется команда 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

Мониторинг RabbitMQ

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

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