Установка
ВНИМАНИЕ: Данная инструкция актуальна для версий ERP USERSIDE 3.19
Описание
В целях упрощения будут рассмотрены команды для операционной системы Linux Debian 12 (bookworm). Для опытных системных администраторов не составит труда использовать аналогичные команды для другой операционной системы. Если же вы не чувствуете себя уверено в администрировании операционных систем, то мы рекомендуем вам использовать операционную систему Debian либо Ubuntu Server LTS. Из-за их простоты, а также по причине того, что наша техническая поддержка значительно лучше разбирается в Debian-подобных дистрибутивах. Вероятность подсказать что-либо не касающееся ERP USERSIDE, но касающееся администрирования операционной системы, будет значительно выше, если у вас будет Debian или подобный дистрибутив на его основе.
С другой стороны, если вы опытный системный администратор и имеете навыки и опыт работы с Docker, возможно для вас будет более удобным вариант использования готового окружения на базе Docker-образов, которые мы подготовили специально, включив в них всё необходимое для работы ERP USERSIDE. В этом случае вам не придется ничего настраивать, кроме как выполнить простые настройки Docker-бандла https://github.com/userside/userside-docker.
Требования
Для работы ERP USERSIDE необходимы различные системные приложения и службы, такие как интерпретатор языка PHP с набором расширений, WEB-сервер, система управления базами данных и прочие. В этом разделе будут перечислены такие требования в зависимости от версии ERP USERSIDE.
Также обратите внимание, что ваша операционная система должна быть сконфигурирована с корректным часовым поясом и локалью. От этого зависит правильность отображения информации и корректность сортировки.
Список требуемых расширений PHP содержит все расширения, не входящие в состав ядра PHP. Часть из этих расширений может поставляться вместе с основным пакетом PHP либо в составе пакета php-common, другая же часть должна быть установлена дополнительно.
3.19 (текущая стабильная)
- PHP: 8.3
- Расширения PHP: ctype, gd, json, libxml, mbstring, openssl, pdo, pdo_pgsql, posix, simplexml, snmp, sockets, zlib, pcntl
- Дополнительные расширения PHP: ldap, soap
- Python: Необходим Python3 любой поддерживаемой на данный момент версии. Статус версий можно посмотреть здесь: "Status of Python versions". Рекомендуется использовать версию с состоянием "security" или "bugfix". Версии отмеченные как "end-of-life" не поддерживаются. Отмеченные как "feature" не рекомендуется использовать.
- Модули Python: pip, venv
- PostgreSQL: 12+ (желательно 16)
- Redis: 5+ (желательно 7)
- RabbitMQ: 3.10+ (желательно 3.13)
- Supervisor
Основные договорённости
Каталог, в который устанавливается ERP USERSIDE - /var/www/userside. Внутри этого каталога должен быть подкаталог public, который является корневым каталогом для WEB-сервера. Если вы хотите использовать другой каталог для ERP USERSIDE, не забывайте вносить соответствующие исправления во все примеры из данной инструкции.
Создайте каталог:
sudo mkdir -p /var/www/userside/public sudo chown -R www-data:www-data /var/www/userside
Вам необходимо выделить доменное имя для ERP USERSIDE. В примерах ниже используется userside.mycompany.com, но вам необходимо будет заменить его на свое. Пропишите это доменное имя в /etc/hosts, если оно отличается от имени хоста, на котором производистя установка.
Установка необходимых компонентов
Сперва установите утилиты, которые будут необходимы далее в процессе установки. Они необходимы для любой верии ERP USERSIDE. Вы можете копировать строки по одной и вставлять их в командную строку вашей операционной системы.
Следующие строки скопируйте и вставьте целиком:
sudo tee /etc/apt/sources.list.d/contrib-non-free.list << EOL deb http://deb.debian.org/debian/ $(lsb_release -sc) contrib non-free non-free-firmware EOL sudo apt update sudo apt full-upgrade -y sudo apt install -y gnupg ca-certificates lsb-release debian-archive-keyring debian-keyring libsnmp-dev snmp-mibs-downloader
PostgreSQL
Альтернативный официальный репозиторий
Мы настоятельно рекомендуем использовать последнюю версию PostgreSQL, так как это всегда положительно сказывается на скорости работы. Добавьте в систему официальный репозиторий Postgres:
sudo install -d /usr/share/postgresql-common/pgdg sudo curl -o /usr/share/postgresql-common/pgdg/apt.postgresql.org.asc --fail https://www.postgresql.org/media/keys/ACCC4CF8.asc sudo sh -c 'echo "deb [signed-by=/usr/share/postgresql-common/pgdg/apt.postgresql.org.asc] https://apt.postgresql.org/pub/repos/apt $(lsb_release -cs)-pgdg main" > /etc/apt/sources.list.d/pgdg.list' sudo apt update
Если у вас другая операционная система, вы можете найти необходимые команды для нее на официальном сайте PostgreSQL.
Установка
Внимание! Перед установкой PostgreSQL в вашей операционной системе должна быть установлена ваша местная локаль и корректный часовой пояс! Это можно сделать и позже, но будет намного проще, если это будет сделано до установки PostgreSQL. Выполните следующую команду, чтобы убедиться, что нужная локаль присутствует:
locale -a
Если среди перечисленных нет вашей местной локали, то установите ее. Для этого достаточно отредактировать файл /etc/locale.gen убрав комментарии перед строкой (строками) с нужной локалью, а затем выполнить команду:
sudo locale-gen
Если вам нужно изменить локаль по умолчанию, то выполните:
sudo dpkg-reconfigure locales
Чтобы изменить часовой пояс, выполните:
sudo timedatectl set-timezone Europe/Kyiv
Теперь можно перейти к установке PostgreSQL:
sudo apt install -y postgresql-16 postgresql-16-postgis-3
Настройка
Создайте пользователя и базу данных для ERP USERSIDE. В примере ниже создается пользователь с именем userside и база данных с таким же именем. Если ваша локаль не uk_UA, не забудьте изменить команду. Затем к базе данных подключается расширение PostGis, необходимое для работы с географическими данными. После выполнения первой строки, вам необходимо будет дважды ввести пароль для нового пользователя - запишите этот пароль, он понадобится вам далее для установки ERP USERSIDE
sudo -u postgres createuser userside -P sudo -u postgres createdb -e -E "UTF-8" -l "uk_UA.UTF-8" -O userside -T template0 userside sudo -u postgres psql -d userside -c "CREATE EXTENSION postgis"
Если ваш PostgreSQL установлен на другом сервере, то вам необходимо будет внести коррекции в файлы postgresql.conf и pg_hba.conf, расположенные в каталоге /etc/postgresql/16/main/. В файле postgresql.conf необходимо раскомментировать и изменить значение параметра listen_addresses, указав там все IP-адреса интерфейсов сервера, на которых он может принимать подключения к PostgreSQL. В файле pg_hba.conf необходимо в самом конце добавить строку по аналогии с предыдущими, указывающую, с какого адреса может подключаться пользователь ERP USERSIDE. Но если ваш PostgreSQL расположен на том же сервере, что и USERSIDE - нет необходимости вносить какие либо корректировки в эти файлы.
Redis
Стандартный репозиторий Debian 12 включает версию Redis 7.0.15. Эта версия подходит для работы ERP USERSIDE.
Установка
sudo apt install -y redis-server
Настройка
По умолчанию Redis принимает подключения без пароля, но мы настоятельно рекомендуем установить пароль. Так как пароль передается в открытом виде (Redis не предусматривает шифрования, т.к. делает упор на скорость обработки запросов и лишние этапы вроде шифрования не применяются), вам нужно создать действительно длинный и сложный пароль, например, используя утилиту openssl следующим образом:
openssl rand --hex 32
На выходе вы получите случайный набор из 32 байт в 16-ричном виде, который и будете использовать в качестве пароля. Далее нужно будет вместо слова MYPASSWORDHERE подставить эту сгенерированную строку. Запишите его. Далее в настройках вы будете указывать эту строку как пароль Redis.
Укажите полученный хэш парольной фразы в конфигурационном файле Redis:
sudo sed -i 's@^.*requirepass .*@requirepass MYPASSWORDHERE@g' /etc/redis/redis.conf
где вместо MYPASSWORDHERE укажите хэш парольной фразы поулченый ранее.
Также необходимо отключить таймаут (на некоторых версиях Redis он включен):
sudo sed -i 's@^timeout .*@timeout 0@' /etc/redis/redis.conf
Перезапустите Redis и убедитесь, что он работает (в ответ должны получить PONG):
sudo systemctl restart redis redis-cli -h 127.0.0.1 -p 6379 -a MYPASSWORDHERE ping
RabbitMQ
Стандартный репозиторий Debian 12 включает старую версию RabbitMQ 3.10. Вы можете использовать ее — она поддерживается. Однако, эта версия относительно старая и лучшим вариантом будет установить новую версию из альтернативных репозиториев. На официальном сайте RabbitMQ находится достаточно подробная информация по установке RabbitMQ для каждой операционной системы.
Добавление альтернативных репозиториев
Следующий блок скопируйте и вставьте целиком в командную строку
curl -1sLf https://dl.cloudsmith.io/public/rabbitmq/rabbitmq-erlang/gpg.E495BB49CC4BBE5B.key | sudo gpg --dearmor | sudo tee /usr/share/keyrings/rabbitmq-erlang-archive-keyring.gpg > /dev/null curl -1sLf https://dl.cloudsmith.io/public/rabbitmq/rabbitmq-server/gpg.9F4587F226208342.key | sudo gpg --dearmor | sudo tee /usr/share/keyrings/rabbitmq-server-archive-keyring.gpg > /dev/null sudo tee /etc/apt/sources.list.d/rabbitmq.list <<EOF deb [signed-by=/usr/share/keyrings/rabbitmq-erlang-archive-keyring.gpg] https://dl.cloudsmith.io/public/rabbitmq/rabbitmq-erlang/deb/debian $(lsb_release -cs) main deb-src [signed-by=/usr/share/keyrings/rabbitmq-erlang-archive-keyring.gpg] https://dl.cloudsmith.io/public/rabbitmq/rabbitmq-erlang/deb/debian $(lsb_release -cs) main deb [signed-by=/usr/share/keyrings/rabbitmq-server-archive-keyring.gpg] https://dl.cloudsmith.io/public/rabbitmq/rabbitmq-server/deb/debian $(lsb_release -cs) main deb-src [signed-by=/usr/share/keyrings/rabbitmq-server-archive-keyring.gpg] https://dl.cloudsmith.io/public/rabbitmq/rabbitmq-server/deb/debian $(lsb_release -cs) main EOF sudo apt update
Установка
Убедитесь, что в /etc/hosts есть запись для имени вашего хоста. Отсутствие такрой записи (например, если вы изменили имя хоста после инсталляции) является основной ошибкой, возникающей при установке RabbitMQ. Так что лучше еще раз убедитесь, что запись соответствующая имени хосту имеется.
sudo apt install -y erlang-base \
erlang-asn1 erlang-crypto erlang-eldap erlang-ftp erlang-inets \
erlang-mnesia erlang-os-mon erlang-parsetools erlang-public-key \
erlang-runtime-tools erlang-snmp erlang-ssl \
erlang-syntax-tools erlang-tftp erlang-tools erlang-xmerl
sudo apt install rabbitmq-server -y --fix-missing
Установка необходимых дополнений
Следующие две строки выполняйте по одной за раз!
sudo rabbitmq-plugins enable rabbitmq_management --offline sudo rabbitmq-plugins enable rabbitmq_web_stomp --offline
Настройка
Скопируйте и вставьте целиком следующий блок:
sudo tee /etc/rabbitmq/rabbitmq.conf << EOF listeners.tcp.default = 5672 web_stomp.port = 15674 web_stomp.cowboy_opts.max_keepalive = 60 EOF
Теперь нужно создать пользователей. Мы рекомендуем использовать три различных пользователя: для администрирования сервера (полные права), для userside и модулей (полные права но без административных) и пользователя web-stomp для websocket (минимальные права на чтение определенных объектов брокера). Но вы можете создать только два: администратора, который также будете использоваться для USERSIDE, и пользователя для websocket. Это обязательно должны быть минимум два разных пользователя, так как пароль для websocket пользователя передается в браузер и может быть легко прочитан пользователем. Далее будет показан пример для рекомендуемых трех пользователей.
Создайте пользователя для администрирования RabbitMQ. В данном примере используется имя пользователя admin и пароль пароль_администратора. Пользователю сразу после создания присваивается тэг administrator, наделяющий пользователя максимальными правами администратора и затем устанавливаются разрешения для vhost / позволяющие полный доступ к конфигурированию, записи и чтению всего в пределах этого vhost*.
sudo rabbitmqctl add_user "admin" "пароль_администратора" sudo rabbitmqctl set_user_tags "admin" "administrator" sudo rabbitmqctl set_permissions -p "/" "admin" ".*" ".*" ".*"
Создайте пользователя, от имени которого будут работать ERP USERSIDE и модули. Пример для имени пользователя userside (наделять админскими правами этого пользователя не нужно):
sudo rabbitmqctl add_user "userside" "пароль_системы" sudo rabbitmqctl set_user_tags "userside" "monitoring" sudo rabbitmqctl set_permissions -p "/" "userside" ".*" ".*" ".*"
Создайте пользователя WebSTOMP. Он понадобится для использования уведомлений через WebSocket. Вместо websock-user вы можете указать другое имя пользователя. Вместо пароль_websocket укажите свой пароль, но этот пароль будет передаваться в открытом виде в браузер, так что не делайте его похожим на остальные пароли:
sudo rabbitmqctl add_user "websock-user" "пароль_websocket" sudo rabbitmqctl set_permissions -p "/" "websock-user" "^erp-stomp:id-.*" "" "^erp-stomp:id-.*"
Внимание! Имя пользователя и пароль WebSTOMP вам нужно будет указать в настройках в интерфейсе USERSIDE (Меню: Настройки - Основные - Websocket).
* vhost - это виртуальный хост внутри RabbitMQ, позволяющий разграничить различные варианты использования одного и того же сервера разными приложениями. Как, например, разные базы данных на одном сервере СУБД. vhost по умолчанию имеет имя / и почти всегда вам этого достаточно. Но если вы планируете, например, запустить несколько копий ERP USERSIDE на одном сервере, то для каждой копии вам нужно будет создать свой vhost и, соответственно, пользователей для него. Подробней обратитесь к официальному руководству.
Перезапустите службу rabbitmq:
sudo systemctl restart rabbitmq-server
Управление
Одна из команд, приведенных выше, устанавливает в RabbitMQ модуль управления, предоставляющий удобный WEB-интерфейс для мониторинга, диагностики и управления сервером RabbitMQ. При помощи этого модуля можно осуществлять мониторинг сервера, следить за количеством сообщений в очередях и другими состояниями. Всё это можно делать и используя консольную утилиту rabbitmqctl, но использование WEB-интерфейса может быть значительно наглядней и удобней.
По умолчанию WEB-интерфейс управления доступен по адресу http://userside.mycompany.com:15672. Рекомендуем использовать фаервол, чтобы ограничить доступ к этому интерфейсу управления.
Подробнее о модуле управления можно прочитать на официальном сайте RabbitMQ.
PHP
Альтернативный репозиторий
sudo curl -sSLo /usr/share/keyrings/deb.sury.org-php.gpg https://packages.sury.org/php/apt.gpg sudo sh -c 'echo "deb [signed-by=/usr/share/keyrings/deb.sury.org-php.gpg] https://packages.sury.org/php/ $(lsb_release -sc) main" > /etc/apt/sources.list.d/php.list' sudo apt update
Установка
Выполните следующие команды:
sudo apt install -y php8.3-{fpm,cli,common,curl,intl,mbstring,opcache,pgsql,readline,xml,zip,snmp,gd}
Если вы планируете использовать LDAP, необходимо установить расширение php-ldap:
sudo apt install -y php8.3-ldap
Если вы планируете использовать отправку SMS используя TurboSMS, также понадобится расширение php-soap:
sudo apt install -y php8.3-soap
Настройка
Далее приведены команды, вносящие изменения в файлы конфигурации.
sudo sed -i "s@^;date.timezone.*@date.timezone = $(cat /etc/timezone)@" /etc/php/8.3/fpm/php.ini sudo sed -i "s@^;date.timezone.*@date.timezone = $(cat /etc/timezone)@" /etc/php/8.3/cli/php.ini sudo sed -i "s@;cgi.fix_pathinfo=1@cgi.fix_pathinfo=0@" /etc/php/8.3/fpm/php.ini sudo sed -i "s@post_max_size = 8M@post_max_size = 100M@" /etc/php/8.3/fpm/php.ini sudo sed -i "s@upload_max_filesize = 2M@upload_max_filesize = 100M@" /etc/php/8.3/fpm/php.ini sudo sed -i "s@max_execution_time.*@max_execution_time = 300@" /etc/php/8.3/fpm/php.ini sudo sed -i "s@^;request_terminate_timeout =.*@request_terminate_timeout = 300@" /etc/php/8.3/fpm/pool.d/www.conf sudo systemctl restart php8.3-fpm
NGINX
Альтернативный официальный репозиторий
Версия NGINX, поставляемая в репозитории Debian, полностью подходит для использования и нет необходимости в добавлении альтернативного репозитория. Однако, если вам хочется всегда иметь последнюю версию, то выполните следующие строки, чтобы добавить в операционную систему официальный репозиторий nginx:
curl https://nginx.org/keys/nginx_signing.key | gpg --dearmor \
| sudo tee /usr/share/keyrings/nginx-archive-keyring.gpg >/dev/null
echo "deb [signed-by=/usr/share/keyrings/nginx-archive-keyring.gpg] \
http://nginx.org/packages/debian `lsb_release -cs` nginx" \
| sudo tee /etc/apt/sources.list.d/nginx.list
echo -e "Package: *\nPin: origin nginx.org\nPin: release o=nginx\nPin-Priority: 900\n" \
| sudo tee /etc/apt/preferences.d/99nginx
sudo apt update
Если у вас другая операционная система, вы можете найти необходимые команды для нее на официальном сайте NGINX: https://docs.nginx.com/nginx/admin-guide/installing-nginx/installing-nginx-open-source/
Установка
sudo apt install -y nginx
Настройка
sudo sed -i "s@^user.*;@user www-data www-data;@" "/etc/nginx/nginx.conf" sudo systemctl restart nginx
Следующий пример настройки подразумевает, что ERP USERSIDE будет установлен в стандартный каталог системы /var/www/userside. Если вы желаете установить ERP USERSIDE в другой каталог, пожалуйста, не забывайте исправлять его во всех последующих примерах. Чтобы не ошибиться, мы рекомендуем использовать именно каталог /var/www/userside.
Теперь отредактируйте файл /etc/nginx/conf.d/default.conf. Либо удалите его и создайте файл с именем /etc/nginx/conf.d/userside.conf. В любом случае, не зависимо от вашего выбора, содержимое файла должно быть следующим (вместо userside.mycompany.com укажите свое доменное имя):
server {
listen 80 default_server;
server_name userside.mycompany.com;
charset utf-8;
client_max_body_size 100M;
access_log /var/log/nginx/userside-access.log;
error_log /var/log/nginx/userside-error.log;
root /var/www/userside/public;
index index.php;
location = /favicon.ico { access_log off; log_not_found off; }
location = /robots.txt { access_log off; log_not_found off; }
location / {
try_files $uri $uri/ /index.php$is_args$args;
}
location ~* ^.+\.(css|js|ogg|ogv|svg|svgz|eot|otf|woff|mp4|ttf|rss|atom|jpg|jpeg|gif|png|ico|zip|tgz|gz|rar|bz2|doc|xls|exe|ppt|tar|mid|midi|wav|bmp|rtf)$ {
access_log off;
log_not_found off;
expires max;
add_header Pragma public;
add_header Cache-Control "public";
}
location ~ \.php$ {
try_files $uri =404;
fastcgi_split_path_info ^(.+\.php)(/.+)$;
fastcgi_pass unix:/run/php/php8.3-fpm.sock;
fastcgi_index index.php;
fastcgi_param SCRIPT_FILENAME $document_root$fastcgi_script_name;
fastcgi_read_timeout 300;
include fastcgi_params;
}
location /ws {
proxy_pass http://127.0.0.1:15674/ws;
proxy_http_version 1.1;
proxy_set_header Upgrade $http_upgrade;
proxy_set_header Connection "Upgrade";
proxy_set_header Host $host;
}
location ~ /\.ht { deny all; }
}
Также, возможно, вы захотите настроить SSL и что-либо еще. Эта тема выходит за рамки данной инстуркции.
Если Вы установили RabbitMQ на другом сервере, либо изменили значение порта WebSTOMP с 15674 на какой-то другой, то укажите IP-адрес сервера с RabbitMQ и номер порта в строке proxy_pass http://127.0.0.1:15674/ws;. Протокол должен оставаться http. Путь должен оставаться /ws.
Проверьте конфигурацию и если она в порядке перезагрузите nginx:
sudo nginx -t && sudo nginx -s reload
Python
Необходим Python3 любой поддерживаемой на данный момент версии. Статус версий можно посмотреть здесь: "Status of Python versions". Рекомендуется использовать версию с состоянием "security" или "bugfix". Версии отмеченные как "end-of-life" не поддерживаются. Отмеченные как "feature" не рекомендуется использовать.
Если у вас на хосте неподдерживаемая версия ("end-of-life"), то нужно обязательно установить дополнительно более свежую версию Python.
Установка необходимых пакетов
sudo apt install -y python3-dev python3-pip python3-venv libffi-dev pkg-config
Supervisor
sudo apt install -y supervisor
Загрузка и запуск инсталлятора
См. также: Справку по инсталлятору
1. перейти в каталог системы
cd /var/www/userside
2. загрузить скрипт-инсталлятор
sudo -u www-data php -r "copy('https://my.userside.eu/install', 'userside_install.phar');"
3. запустить инсталлятор
sudo -u www-data php userside_install.phar install
В процессе работы инсталлятор проверяет соответствие техническим требованиям, запрашивает параметры доступа и проверяет соединения со службами сервера.
Вы можете ввести любой доступный вам номер версии ERP USERSIDE для установки. Для этого можете ввести порядковый номер версии из списка (он содержит только последние версии каждой ветки) либо ввести номер версии целиком, если ее нет в списке.
По окончанию работы инсталлятора будет выведено сообщение об успешной установке.
Если вы произвели установку не от имени пользователя веб-сервера, то обязательно после окончания установки сделайте его владельцем всех файлов userside рекурсивно!
sudo chown -R www-data:www-data /var/www/userside sudo chmod -R u=rwX,g=rwX,o=r /var/www/userside
Настройка после установки
Конфигурация системных служб
После установки необходимо скопировать примеры конфигурационных файлов системных служб и, при необходимости, настроить их (например, указать путь к каталогу userside, если он отличается от /var/www/userside). Выполните команды:
sudo cp etc/us-core-worker.conf-example /etc/supervisor/conf.d/us-core-worker.conf sudo cp microservice/poller/etc/usm_poller.conf-example /etc/supervisor/conf.d/usm_poller.conf sudo cp etc/logrotate-example /etc/logrotate.d/userside sudo cp microservice/poller/etc/logrotate-example /etc/logrotate.d/usm_poller sudo cp etc/crontab-example /etc/cron.d/userside
Установка необходимых зависимостей для usm_poller
Создайте виртуальное окружение venv для python и установите зависимые модули, как показано далее:
cd /var/www/userside/microservice/poller sudo -H python3 -m venv venv sudo -H venv/bin/pip install -U pip sudo -H venv/bin/pip install -U -r requirements.txt
Запуск супервизора
Супервизор контролирует работу служб, указанных в его конфигурации. Для запуска супервизора выполните:
sudo systemctl restart supervisor
После запуска супервизора, спустя несколько секунд можно понаблюдать за состоянием всех контролируемых им служб. Все службы должны быть в состоянии RUNNING:
sudo supervisorctl status
Сразу после установки
На этом установка ERP USERSIDE закончена. Теперь выполните следующие шаги:
- Откройте страницу системы http://userside.mydomain.com/ и выполните вход (по умолчанию имя пользователя: Admin, пароль: 1234).
- Выполните настройку Websocket в разделе: Настройка - Основная - WebSocket. Включите и впишите имя пользователя и пароль WebStomp пользователя, которого вы создавали ранее в разделе RabbitMQ.
- Выполните основные настройки в разделе: Настройка - Основная.
- Настройте взаимодействие с биллингом в соответствии с инструкциями.
- Ознакомьтесь с инструкциями на странице: С чего начать?.
- Настройте API-ключ.
Обновление системы
Мы стараемся делать все возможное, чтобы вероятность сквоздного обновления с любой версии до последней версии было успешным. Однако, иногда бывает так, что из-за каки-то старинных проблем со структурой базы данных, которые никогда не мешали работать раньше, может возникнуть ситуация, при которой сквоздное обновление невозможно. В таком случае вам придется обновляться поэтапно на каждую следующую последнюю версию. Например, с 3.14.80 сначала на 3.15.60, затем на 3.16.39 и так далее.
Перед обновлением обязательно прочитайте обо всех изменениях, которые необходимо выполнить для обновления для каждой версии, которая лежит между вашей и той, на которую вы собираетесь обновиться.
Мы рекомендуем сделать копию системы для безопасного проведения обновления. Обратитесь к разделу HOWTO: Клонирование USERSIDE. Вы всегда можете удалить копию и начать сначала. Это просто и безопасно. Но если вы желаете обновить работающую систему, то выполняйте его в моменты наименьшей нагрузки с запасом по времени, необходимым для аварийного восстановления, если вдруг что-то пойдет не так. Всегда обязательно делайте резервную копию базы данных и файлов перед обновлениями. Если обновление будет прервано, особенно на этапе миграции данных, то есть риск того, что восстановить корректно данные будет очень непросто или даже невозможно. В общем, ответственность за наличие актуальной резервной копии лежит целиком на вас.
Процесс обновления
Мы настоятельно рекомендуем выполнять тестовые обновления на копии системы.
Для проведения обновления запустите инсталлятор в режиме install и следуйте инструкциям:
cd /var/www/userside sudo -u www-data php userside_install.phar install
После обновления USERSIDE нужно обязательно обновить зависимости usm_poller:
cd /var/www/userside/microservice/poller sudo -H venv/bin/pip install -U pip sudo -H venv/bin/pip install -U -r requirements.txt
Теперь нужно перезапустить все службы, которолируемые супервизором и проследить чтобы все они запустились и были в состоянии RUNNING:
sudo supervisorctl restart all sudo supervisorctl status
Обслуживание системы
Для поддержания системы в рабочем состоянии и обеспечения надежной ее работы в будущем рекомендуется выполнять несколько простых дейсвтий:
- периодически создавать резервную копию базы данных
- периодически создавать резервную копию загруженных файлов (это можно сделать просто архивируя каталог /var/www/userside/var/attachments и файл .env)
- периодически наблюдать за производительностью сервера (при помощи htop, atop) и брокера RabbitMQ и принимать решения о масштабировании пулов fpm, фоновых процессов ядра и микросервисов
Резервное копирование
Установите периодическое резервное копирование базы данных и пользовательских файлов. Желательно минимум раз в сутки в моменты наименьшей нагрузки на сервер. В PostgreSQL существует два способа создать резервную копию базы данных: dump и sql-script. У каждого из них есть свои преимущества и недостатки. Первый создает безопасный дамп базы данных целиком, а второй создает SQL-скрипт, выполняя который можно восстановить как структуру так и данные. Рекомендуем обратиться к документации по использованию команды pg_dump для выбора более подходящего для вас способа или набора параметров.
Ниже приведены две команды для создания резервной копии базы данных — выбирайте одну из них и добавляйте в ваш crontab:
# SQL-script sudo -u postgres pg_dump --no-acl -Fp -Z 5 userside > /backup/userside.sql.gz # DUMP sudo -u postgres pg_dump --no-acl -Fc userside > /backup/userside.dump
Для создания минимальной резервной копии файлов можно использовать следующую команду (для версии 3.15 и новее):
sudo tar -czf /backup/userside.tgz .env common/config/settings.json var/attachments
Этих файлов вместе с базой данных будет достаточно для восстановления работы USERSIDE. Но вы можете выполнять резервное копирование всего каталога /var/www/userside для большей надежности.
Восстановление из резервной копии
Для восстановления из дампа используется команда pg_restore. Документация по использованию pg_restore. Для восстановления из SQL-скрипта используется утилита psql. Документация по использованию psql.
SQL-script
Для восстановления БД из резервной копии в виде SQL-скрипта, сначала нужно пересоздать базу данных, а затем восстановить в пустую базу данных резервную копию:
sudo -u postgres dropdb userside sudo -u postgres createdb -e -E "UTF-8" -l "uk_UA.UTF-8" -O userside -T template0 userside sudo -u postgres psql -d userside -c "CREATE EXTENSION postgis" gunzip < userside.sql.gz | sudo -u postgres psql -d userside -v ON_ERROR_STOP=1
DUMP
Дамп содержит целиком базу данных со всеми ее элементами. Поэтому перед восстановлением базы данных из дампа её не должно существовать на сервере — удалите базу данных перед восстановлением из дампа. Также важно, чтобы пользователь базы данных (владелец всех элементов) уже существовал — создайте его перед восстановлением, если вы восстанавливаете базу данных на новом сервере, где нужного пользователя еще нет.
Также обратите внимание, что структура дампа может быть несовместима между разными версиями PostgreSQL. Это не обязательно так, но вполне вероятно.
Для восстановления из дампа используйте команды:
sudo -u postgres dropdb userside sudo -u postgres pg_restore --clean --if-exists --create --exit-on-error --dbname=postgres userside.dump
Обратите внимание, что имя базы данных в команде обязательно должно быть postgres, так как из дампа восстанавливается вся база данных целиком, а не ее содержимое.
После восстановления базы данных
После восстановления базы данных любым способом, необходимо очистить кэш ERP USERSIDE, т.к. в кэше теперь находятся данные, отличные от данных в базе. Перейтите в каталог /var/www/userside и выполните команду очистки кэша:
cd /var/www/userside php run cache/flush-all
И выполните команду восстановления, которая в том числе проверит систему на целостность.
sudo -u www-data php userside_install.phar repair