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

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

Подготовительные работы

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

• убедитесь, что ваша система соответствует необходимым техническим требованиям.

• установите 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):

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"
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.

 sudo mkdir -p /var/www/userside/userside3

• создайте сайт для nginx (или отредактируйте имеющийся сайт по умолчанию). Для этого создайте файл /etc/nginx/conf.d/userside.conf и поместите в него текст:

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.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 и расширения Postgis

• выполните установку и/или настройку 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 выполнена, перейдите к оптимизации пула PHP-FPM. По умолчанию за настройку пула отвечает файл /etc/php/7.2/fpm/pool.d/www.conf

Этот файл содержит несколько настроек менеджера процессов (PM), которые начинаются с pm

Мы рекомендуем использовать динамический пул, так как на одном сервере работают и другие службы. В этом случае менеджер процессов будет управлять количеством процессов php-fpm в памяти автоматически, высвобождая ресурсы, если в них нет необходимости. По умолчанию менеджер процессов работает именно в этом режиме, но на всякий случай убедитесь, что это именно так: pm = dynamic

Далее необходимо настроить количество процессов 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. Такое максимальное количество воркеров мы можем запустить.

Указываем в качестве значения pm.max_children = 7.

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

pm.min_spare_servers = 2
pm.max_spare_servers = 4

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

Итого, настройка менеджера процессов пула PHP-FPM будет следующей:

pm.max_children = 7
pm.min_spare_servers = 2
pm.max_spare_servers = 4 
pm.start_servers = 3

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

Также рекомендуем наблюдать за файлом журнала php-fpm на предмет проблем с воркерами.

tail -f /var/log/php7.2-fpm.log

Об этом могут говорить строки вроде следующей:

WARNING: [pool www] server reached pm.max_children setting (5), consider raising it

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

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

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

cd /var/www/userside

2) запустить команду

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

3) запустить инсталлятор от имени пользователя, под которым работает web-сервер (www-data, но может быть и другим)

sudo -u www-data php userside_install.phar install

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

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

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

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

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

sudo -u www-data php userside_install.phar repair

Если проблему не удается решить самостоятельно - подайте тикет в техническую поддержку

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

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

Настройка системы

• открыть страницу системы http://userside.mydomain.com/oper/ и убедиться в работоспособности системы (имя пользователя: Admin, пароль: 1234)

• доступ к файлу API "/userside/userside3/api.php" рекомендуется ограничить на уровне веб-сервера для доступа лишь с разрешённых IP-адресов

• прописать планировщик UserSide в cron.

cat << EOF > /etc/cron.d/userside
* * * * *   www-data   php /var/www/userside/userside cron > /dev/null 2>&1
EOF

• настроить взаимодействие с биллингом в соответствии с инструкциями

• в разделе "Настройка - Основная" изучите основные разделы, параметры и настройте систему под себя.

Резервное копирование, восстановление, клонирование

Крайне рекомендуется после установки системы установить периодическое (лучше - ежедневное) создание резервной копии штатными средствами PostgeSQL и её хранение НА ДРУГОМ узле. Например:

sudo -u postgres pg_dump --no-acl -Fc userside > /backup/userside.dump

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

Перед восстановлением базы данных необходимо обязательно очистить кеш Redis (только для версии 3.13 и новее)

php userside cache/flush-all

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

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

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

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

Выполнив эту команду произойдет восстановление из дампа в базу данных с именем userside (а не с тем именем, которое в дампе).

Если после восстановления базы данных отсутствуют права на таблицы из схемы public (такое может быть на некоторых отдельных версиях postgresql), назначьте привилегии для схемы public вручную (именно так, не изменяйте эти строки!):

GRANT ALL ON SCHEMA public TO postgres;
GRANT ALL ON SCHEMA public TO PUBLIC;

Если вам необходимо скопировать существующую базу данных для тестирования новых версий или других целей, то используйте для этого команду создания базы данных:

sudo -u postgres createdb -e --encoding="UTF-8" --locale="ru_RU.UTF-8" --owner=userside --template=userside userside_new

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

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

Рекомендуется ознакомиться с инструкциями на странице: С чего начать?

Отдельно стоит отметить резервное копирование прикрепленных файлов в системе. С течением времени объем прикреплённых файлов будет расти и достигать больших величин. Поэтому резервное копирование будет долгим и избыточным, хотя и необходимым. Обдумайте как настроить периодический бэкап файлов из директории /userside/ (возможно следует настроить бэкап только обновлённых файлов)

Копия системы для тестирования или исследований

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

• скопируйте файлы приложения

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

• скопируйте базу данных (или создайте новую базу данных и восстановите ее из резервной копии):

sudo -u postgres createdb -e --encoding="UTF-8" --locale="ru_RU.UTF-8" --owner=userside --template=userside userside_new

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

sudo -u postgres createuser userside -P

• В версии 3.13 и новее перейдите в каталог с новой копией, отредактируйте переменные окружения в файле .env таким образом, чтобы они работали с новой базой данных и с другой (свободной) базой данных redis (в основной инсталляции у вас, скорее всего, используется база данных redis под номером 0; вы можете использовать еще 15, имеющихся по умолчанию). За это отвечают переменные:

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

• теперь можно открыть в браузере вашу копию.

Частозадаваемые вопросы (FAQ)

Ошибка 404 при проверке URL. Вероятней всего неверно настроен WEB-сервер. root (DocumentRoot) WEB-сервера должен указывать на каталог /var/www/userside/userside3