Встановлення

Материал из WiKi - UserSide

en | uk | ru

УВАГА: ця інструкція актуальна для версій ERP USERSIDE 3.19+

Опис

Для спрощення будуть розглянуті команди для операційної системи Linux Debian 13 (trixie). Для досвідчених системних адміністраторів не становитиме труднощів використати аналогічні команди для іншої операційної системи. Якщо ж ви не почуваєтеся впевнено в адмініструванні операційних систем, ми рекомендуємо використовувати 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.20

  • PHP 8.4-8.5
  • Розширення PHP: ctype, gd, json, libxml, mbstring, openssl, pdo, pdo_pgsql, posix, simplexml, snmp, sockets, zlib, pcntl
  • Додаткові розширення PHP: ldap
  • Python: Потрібен Python3 будь-якої версії, що підтримується на цей момент. Статус версій можна переглянути тут: "Status of Python versions". Рекомендується використовувати версію зі станом "security" або "bugfix". Версії, позначені як "end-of-life", не підтримуються. Версії, позначені як "feature", використовувати не рекомендується.
  • Модулі Python: pip, venv
  • PostgreSQL: 16+ (бажано 18)
  • Redis: 5+ (бажано 7)
  • RabbitMQ: 3.13+ (бажано 4+)
  • Supervisor

3.19 (поточна стабільна)

  • PHP: 8.3-8.4
  • Розширення 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 /var/log/usm_poller
sudo chown -R www-data:www-data /var/www/userside /var/log/usm_poller

Вам потрібно виділити доменне ім'я для 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-18 postgresql-18-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 13 містить Redis версії 8.0.2. Ця версія підходить для роботи ERP USERSIDE.

Встановлення

sudo apt install -y redis-server

Налаштування

За замовчуванням Redis приймає підключення без пароля, але ми наполегливо рекомендуємо встановити пароль. Оскільки пароль передається у відкритому вигляді (Redis не передбачає шифрування, бо орієнтований на швидкість обробки запитів, і додаткові кроки на кшталт шифрування не застосовуються), потрібно створити справді довгий і складний пароль, наприклад за допомогою утиліти openssl: 

openssl rand --hex 32

На виході буде випадковий набір із 32 байтів у шістнадцятковому вигляді, який ви використовуватимете як пароль. Далі потрібно підставити цей згенерований рядок замість слова MYPASSWORDHERE. Запишіть його. Потім ви вкажете цей рядок як пароль Redis у налаштуваннях.

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

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

де замість MYPASSWORDHERE вкажіть отриманий раніше пароль.

Також слід вимкнути timeout (у деяких версіях 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 13 містить старішу версію RabbitMQ 4.0.5. Її можна використовувати - вона підтримується. Однак ця версія відносно стара, тому краще встановити новішу версію з альтернативних репозиторіїв. На офіційному сайті RabbitMQ є досить докладна інформація щодо встановлення RabbitMQ для кожної операційної системи.

Додавання альтернативних репозиторіїв

Скопіюйте та вставте такий блок повністю в командний рядок: 

curl -1sLf "https://keys.openpgp.org/vks/v1/by-fingerprint/0A9AF2115F4687BD29803A206B73A36E6026DFCA" \
  | sudo gpg --dearmor \
  | sudo tee /usr/share/keyrings/com.rabbitmq.team.gpg > /dev/null

sudo tee /etc/apt/sources.list.d/rabbitmq.list <<EOF
deb [arch=amd64 signed-by=/usr/share/keyrings/com.rabbitmq.team.gpg] https://deb1.rabbitmq.com/rabbitmq-server/debian/trixie trixie main
deb [arch=amd64 signed-by=/usr/share/keyrings/com.rabbitmq.team.gpg] https://deb2.rabbitmq.com/rabbitmq-server/debian/trixie trixie main
EOF

sudo apt update

Встановлення

Переконайтеся, що в /etc/hosts є запис для вашого hostname. Відсутність такого запису (наприклад, якщо ви змінили hostname після встановлення) є типовою помилкою під час встановлення RabbitMQ. Тому краще ще раз переконатися, що запис для hostname є. 

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

consumer_timeout = 2400000

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

Тепер потрібно створити користувачів. Ми рекомендуємо використовувати трьох різних користувачів: для адміністрування сервера (повні права), для userside і модулів (повні права, але без адміністративних прав) і користувача web-stomp для websocket (мінімальні права на читання певних об'єктів брокера). Але можна створити лише двох: адміністратора, який також використовуватиметься для userside, і користувача для websocket. Обов'язково має бути щонайменше два різні користувачі, оскільки пароль користувача websocket передається в браузер і може бути легко прочитаний користувачем. Далі наведено приклад для рекомендованих трьох користувачів.

Створіть користувача для адміністрування RabbitMQ. У цьому прикладі використовується ім'я користувача admin і пароль admin_password. Тег administrator призначається користувачу одразу після створення, надаючи максимальні адміністративні права, а потім задаються дозволи для vhost /, що дозволяють повний доступ до налаштування, запису й читання всього всередині цього vhost*. 

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

Створіть користувача, від імені якого працюватимуть ERP USERSIDE і модулі. Приклад для імені користувача userside (адміністративні права цьому користувачу надавати не потрібно): 

sudo rabbitmqctl add_user "userside" "system_password"
sudo rabbitmqctl set_user_tags "userside" "monitoring"
sudo rabbitmqctl set_permissions -p "/" "userside" ".*" ".*" ".*"

Створіть користувача WebSTOMP. Він знадобиться для використання сповіщень через WebSocket. Замість websock-user можна вказати інше ім'я користувача. Замість password_websocket вкажіть свій пароль, але цей пароль передаватиметься у відкритому вигляді в браузер, тому не робіть його схожим на інші паролі: 

sudo rabbitmqctl add_user "websock-user" "password_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. Ми рекомендуємо використовувати firewall для обмеження доступу до цього інтерфейсу керування.

Докладніше про модуль керування можна прочитати на офіційному сайті 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.4-{fpm,cli,common,curl,intl,mbstring,opcache,pgsql,readline,xml,zip,snmp,gd}

Якщо ви плануєте використовувати LDAP, потрібно встановити розширення php-ldap: 

sudo apt install -y php8.4-ldap

Налаштування

Нижче наведені команди, які вносять зміни до конфігураційних файлів. 

sudo sed -i "s@^;date.timezone.*@date.timezone = $(cat /etc/timezone)@" /etc/php/8.4/fpm/php.ini
sudo sed -i "s@^;date.timezone.*@date.timezone = $(cat /etc/timezone)@" /etc/php/8.4/cli/php.ini
sudo sed -i "s@;cgi.fix_pathinfo=1@cgi.fix_pathinfo=0@" /etc/php/8.4/fpm/php.ini
sudo sed -i "s@post_max_size = 8M@post_max_size = 100M@" /etc/php/8.4/fpm/php.ini
sudo sed -i "s@upload_max_filesize = 2M@upload_max_filesize = 100M@" /etc/php/8.4/fpm/php.ini
sudo sed -i "s@max_execution_time.*@max_execution_time = 300@" /etc/php/8.4/fpm/php.ini
sudo sed -i "s@^;request_terminate_timeout =.*@request_terminate_timeout = 300@" /etc/php/8.4/fpm/pool.d/www.conf

sudo systemctl restart php8.4-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|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|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.4-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. завантажте скрипт інсталятора 

curl -fsSL https://my.userside.eu/install.sh | sudo -u www-data bash

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

sudo -u www-data ./installer install

Під час роботи інсталятор перевіряє відповідність технічним вимогам, запитує параметри доступу та перевіряє підключення до серверних служб.

Ви можете ввести будь-який доступний вам номер версії ERP USERSIDE для встановлення. Для цього можна ввести номер версії зі списку (у ньому міститься лише остання версія кожної гілки) або ввести повний номер версії, якщо його немає у списку.

Після завершення роботи інсталятора буде показано повідомлення про успішне встановлення.

Якщо встановлення виконувалося не від імені користувача web-сервера, після завершення встановлення обов'язково зробіть цього користувача власником усіх файлів userside рекурсивно. 

sudo chown -R www-data:www-data /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

Запуск supervisor

Supervisor контролює роботу служб, зазначених у його конфігурації. Щоб запустити supervisor, виконайте: 

sudo systemctl restart supervisor

Після запуску supervisor за кілька секунд можна переглянути стан усіх служб, які він контролює. Усі служби мають бути в стані RUNNING: 

sudo supervisorctl status

Одразу після встановлення

На цьому встановлення ERP USERSIDE завершено. Тепер виконайте такі дії:

  • Відкрийте сторінку системи http://userside.mydomain.com/ і увійдіть (типовий логін: Admin, пароль: 1234).
  • Налаштуйте Websocket у розділі: Налаштування - Основні - WebSocket. Увімкніть його та введіть ім'я користувача й пароль WebSTOMP-користувача, якого ви створили раніше в RabbitMQ.
  • Виконайте основні налаштування в розділі: Налаштування - Основні.
  • Налаштуйте взаємодію з білінгом згідно з інструкцією.
  • Прочитайте інструкції на сторінці: З чого почати?.
  • Налаштуйте API Key.

Оновлення системи

Ми намагаємося зробити все можливе, щоб наскрізне оновлення з будь-якої версії до останньої версії було успішним. Однак іноді через давні проблеми зі структурою бази даних, які раніше ніколи не заважали роботі, може виникнути ситуація, коли наскрізне оновлення неможливе. У такому випадку доведеться оновлюватися поетапно до кожної наступної останньої версії. Наприклад, з 3.14.80 спочатку до 3.15.60, потім до 3.16.39 і так далі.

Перед оновленням обов'язково прочитайте про всі зміни, які потрібно виконати для оновлення для кожної версії, що лежить між вашою поточною версією та тією, до якої ви збираєтеся оновитися.

Ми рекомендуємо зробити копію системи для безпечного проведення оновлення. Зверніться до розділу HOWTO: Клонування USERSIDE. Ви завжди можете видалити копію та почати спочатку. Це просто й безпечно. Але якщо ви хочете оновити робочу систему, виконуйте оновлення в моменти найменшого навантаження із запасом часу, потрібним для аварійного відновлення, якщо раптом щось піде не так. Завжди обов'язково робіть резервну копію бази даних і файлів перед оновленнями. Якщо оновлення буде перерване, особливо на етапі міграції даних, є ризик, що коректно відновити дані буде дуже непросто або навіть неможливо. Загалом відповідальність за наявність актуальної резервної копії повністю лежить на вас.

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

Ми наполегливо рекомендуємо виконувати тестові оновлення на копії системи.

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

cd /var/www/userside
sudo -u www-data ./installer 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

Тепер потрібно перезапустити всі служби, які контролюються supervisor, і переконатися, що всі вони запустилися та перебувають у стані 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.

Перед відновленням бази даних із резервної копії потрібно обов'язково зупинити роботу USERSIDE.

1. Зупинити cron userside і всіх модулів 

mkdir -p ~/cron
sudo mv /etc/cron.d/userside ~/cron
sudo mv /etc/cron.d/userside-modules ~/cron

2. Зупинити роботу фонових служб 

sudo supervisorctl stop all

3. Зупинити роботу php-fpm 

sudo systemctl stop php8.4-fpm

Тільки після цього можна переходити до відновлення бази даних із резервної копії.

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 і виконайте команду очищення кешу (першу, якщо використовується пароль, або другу, якщо пароль не використовується): 

source /var/www/userside/.env && redis-cli -h $US_REDIS_HOST -p $US_REDIS_PORT -a $US_REDIS_PASSWORD -n $US_REDIS_DB FLUSHDB
source /var/www/userside/.env && redis-cli -h $US_REDIS_HOST -p $US_REDIS_PORT -n $US_REDIS_DB FLUSHDB

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

sudo mv ~/cron/* /etc/cron.d
sudo supervisorctl start all
sudo systemctl start php8.4-fpm

Виконайте команду відновлення, щоб файли системи відповідали версії бази даних і щоб перевірити систему на цілісність файлів. 

cd /var/www/userside
sudo -u www-data ./installer repair
Источник — https://wiki.userside.eu/index.php?title=Встановлення&oldid=22086