WiKi - UserSide - Вклад [ru]

Python-update

2026-02-24T10:29:38Z

Uscld2:

[[Python-update_EN|en]] | [[Python-update|ru]]

Если версия Python, установленная на вашей ОС, не поддерживается модулями или поллером, то необходимо установить дополнительно новую версию Python, удовлетворяющую всем требованиям.

Важно: Изменять системную версию Python на новую - не рекомендуется! Единственный правильный способ - это установить новую версию параллельно системной. Иначе могут перестать работать различные системные службы и утилиты, использующие Python.

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

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

После того, как все установлено, зайдите на сайт https://www.python.org/downloads/source/ и скопируйте номер последней версии текущей ветки или предыдущей, если текущая ветка слишком свежая. Например, если последняя версия 3.14.1, то надежней все таки установить версию 3.13.12, т.к. сразу после выхода новой версии (3.14) есть вероятность того, что не все зависимые пакеты ее поддерживают.

Далее вам нужно создать временную переменную окружения, значение которой будет содержать номер версии Python, которую вы собираетесь установить.

PY_VER=3.13.12

Далее приведены команды, которые вы просто выполняете по одной, одну за другой, чтобы контролировать процесс и в случае ошибки не выполнять остальные команды. Копируйте по одной строке и выполняйте:
curl -o python.tgz "https://www.python.org/ftp/python/${PY_VER}/Python-${PY_VER}.tgz"
tar xzf python.tgz
cd Python-${PY_VER}
./configure --enable-optimizations
make -j $(nproc)
sudo -H make altinstall
curl -sS https://bootstrap.pypa.io/get-pip.py | sudo -H python3.13
cd ..
sudo rm -rf Python-${PY_VER} python.tgz

После выполнения всех этих действий у вас в системе будет установлена дополнительно еще одна версия Python. В данном случае это Python 3.13 а также инструмент pip тоже с версией 3.13. Системная версия Python изменена не будет и мы не рекомендуем ее изменять, так как некоторые системные компоненты могут быть зависимы от нее.

Чтобы использовать именно эту версию python и pip, вам нужно указывать целиком имена файлов, которые вы запускаете. Например:
python3.13 --version
pip3.13 --version

Теперь, чтобы создать виртуальное окружение для какого-либо модуля либо поллера, вам нужно использовать следующий синтаксис:
sudo python3.13 -m venv venv
sudo venv/bin/pip install -U pip wheel
и т.д.

Python-update

2025-10-22T10:14:03Z

Uscld2:

[[Python-update_EN|en]] | [[Python-update|ru]]

Если версия Python, установленная на вашей ОС, не поддерживается модулями или поллером, то необходимо установить дополнительно новую версию Python, удовлетворяющую всем требованиям.

Важно: Изменять системную версию Python на новую - не рекомендуется! Единственный правильный способ - это установить новую версию параллельно системной. Иначе могут перестать работать различные системные службы и утилиты, использующие Python.

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

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

После того, как все установлено, зайдите на сайт https://www.python.org/downloads/source/ и скопируйте номер последней версии текущей ветки или предыдущей, если текущая ветка слишком свежая. Например, если последняя версия 3.14.1, то надежней все таки установить версию 3.13.9, т.к. сразу после выхода новой версии (3.14) есть вероятность того, что не все зависимые пакеты ее поддерживают.

Далее вам нужно создать временную переменную окружения, значение которой будет содержать номер версии Python, которую вы собираетесь установить.

PY_VER=3.13.9

Далее приведены команды, которые вы просто выполняете по одной, одну за другой, чтобы контролировать процесс и в случае ошибки не выполнять остальные команды. Копируйте по одной строке и выполняйте:
curl -o python.tgz "https://www.python.org/ftp/python/${PY_VER}/Python-${PY_VER}.tgz"
tar xzf python.tgz
cd Python-${PY_VER}
./configure --enable-optimizations
make -j $(nproc)
sudo -H make altinstall
curl -sS https://bootstrap.pypa.io/get-pip.py | sudo -H python3.13
cd ..
sudo rm -rf Python-${PY_VER} python.tgz

После выполнения всех этих действий у вас в системе будет установлена дополнительно еще одна версия Python. В данном случае это Python 3.13 а также инструмент pip тоже с версией 3.13. Системная версия Python изменена не будет и мы не рекомендуем ее изменять, так как некоторые системные компоненты могут быть зависимы от нее.

Чтобы использовать именно эту версию python и pip, вам нужно указывать целиком имена файлов, которые вы запускаете. Например:
python3.13 --version
pip3.13 --version

Теперь, чтобы создать виртуальное окружение для какого-либо модуля либо поллера, вам нужно использовать следующий синтаксис:
sudo python3.13 -m venv venv
sudo venv/bin/pip install -U pip wheel
и т.д.

Python-update

2025-10-22T10:00:17Z

Uscld2:

[[Python-update_EN|en]] | [[Python-update|ru]]

Если версия Python, установленная на вашей ОС, не поддерживается модулями или поллером, то необходимо установить дополнительно новую версию Python, удовлетворяющую всем требованиям.

Важно: Изменять системную версию Python на новую - не рекомендуется! Единственный правильный способ - это установить новую версию параллельно системной. Иначе могут перестать работать различные системные службы и утилиты, использующие Python.

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

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

После того, как все установлено, зайдите на сайт https://www.python.org/downloads/source/ и скопируйте номер последней версии текущей ветки или предыдущей, если текущая ветка слишком свежая. Например, если последняя версия 3.14.1, то надежней все таки установить версию 3.13.9, т.к. сразу после выхода новой версии (3.14) есть вероятность того, что не все зависимые пакеты ее поддерживают.

Далее вам нужно создать временную переменную окружения, значение которой будет содержать номер версии Python, которую вы собираетесь установить.

PY_VER=3.13.9

Далее приведены команды, которые вы просто выполняете по одной, одну за другой, чтобы контролировать процесс и в случае ошибки не выполнять остальные команды. Копируйте по одной строке и выполняйте:
curl -o python.tgz "https://www.python.org/ftp/python/${PY_VER}/Python-${PY_VER}.tgz"
tar xzf python.tgz
cd Python-${PY_VER}
./configure --enable-optimizations
make -j $(nproc)
sudo -H make altinstall
curl -sS https://bootstrap.pypa.io/get-pip.py | sudo -H python3.13
cd ..
sudo rm -rf Python-${PY_VER} python.tgz

После выполнения всех этих действий у вас в системе будет установлена дополнительно еще одна версия Python. В данном случае это Python 3.13 а также инструмент pip тоже с версией 3.13. Системная версия Python изменена не будет и мы не рекомендуем ее изменять, так как некоторые системные компоненты могут быть зависимы от нее.

Чтобы использовать именно эту версию python и pip, вам нужно указывать целиком имена файлов, которые вы запускаете. Например:
python3.13 --version
pip3.13 --version

Теперь, чтобы создать виртуальное окружение для какого-либо модуля либо поллера, вам нужно использовать следующий синтаксис:
sudo python3.13 -m venv venv
sudo venv/bin/pip install -U pip wheel
и т.д.

Python-update

2025-10-22T09:54:39Z

Uscld2:

[[Python-update_EN|en]] | [[Python-update|ru]]

Если версия Python, установленная на вашей ОС, не поддерживается модулями или поллером, то необходимо установить дополнительно новую версию Python, удовлетворяющую всем требованиям.

Важно: Изменять системную версию Python на новую - не рекомендуется! Единственный правильный способ - это установить новую версию параллельно системной. Иначе могут перестать работать различные системные службы и утилиты, использующие Python.

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

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

После того, как все установлено, зайдите на сайт https://www.python.org/downloads/source/ и скопируйте номер последней версии текущей ветки или предыдущей, если текущая ветка слишком свежая. Например, если последняя версия 3.14.1, то надежней все таки установить версию 3.13.9, т.к. сразу после выхода новой версии (3.14) есть вероятность того, что не все зависимые пакеты ее поддерживают.

Далее вам нужно создать временную переменную окружения, значение которой будет содержать номер версии Python, которую вы собираетесь установить.

PY_VER=3.13.9

Далее приведены команды, которые вы просто выполняете по одной, одну за другой, чтобы контролировать процесс и в случае ошибки не выполнять остальные команды. Копируйте по одной строке и выполняйте:
curl -o python.tgz "https://www.python.org/ftp/python/${PY_VER}/Python-${PY_VER}.tgz"
tar xzf python.tgz
cd Python-${PY_VER}
./configure --enable-optimizations
make -j $(nproc)
sudo -H make altinstall
curl -sS https://bootstrap.pypa.io/get-pip.py | sudo -H python3.12
cd ..
sudo rm -rf Python-${PY_VER} python.tgz

После выполнения всех этих действий у вас в системе будет установлена дополнительно еще одна версия Python. В данном случае это Python 3.13 а также инструмент pip тоже с версией 3.13. Системная версия Python изменена не будет и мы не рекомендуем ее изменять, так как некоторые системные компоненты могут быть зависимы от нее.

Чтобы использовать именно эту версию python и pip, вам нужно указывать целиком имена файлов, которые вы запускаете. Например:
python3.13 --version
pip3.13 --version

Теперь, чтобы создать виртуальное окружение для какого-либо модуля либо поллера, вам нужно использовать следующий синтаксис:
sudo python3.13 -m venv venv
sudo venv/bin/pip install -U pip wheel
и т.д.

Python-update

2025-10-22T09:53:04Z

Uscld2:

[[Python-update_EN|en]] | [[Python-update|ru]]

Если версия Python, установленная на вашей ОС, не поддерживается модулями или поллером, то необходимо установить дополнительно новую версию Python, удовлетворяющую всем требованиям.

Важно: Изменять системную версию Python на новую - не рекомендуется! Единственный правильный способ - это установить новую версию параллельно системной. Иначе могут перестать работать различные системные службы и утилиты, использующие Python.

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

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

После того, как все установлено, зайдите на сайт https://www.python.org/downloads/source/ и скопируйте номер последней версии текущей ветки или предыдущей, если текущая ветка слишком свежая. Например, если последняя версия 3.14.1, то надежней все таки установить версию 3.13.9, т.к. сразу после выхода новой версии (3.14) есть вероятность того, что не все зависимые пакеты ее поддерживают.

Далее вам нужно создать временную переменную окружения, значение которой будет содержать номер версии Python, которую вы собираетесь установить.

PY_VER=3.13.9

Далее приведены команды, которые вы просто выполняете по одной, одну за другой, чтобы контролировать процесс и в случае ошибки не выполнять остальные команды. Копируйте по одной строке и выполняйте:
curl -o python.tgz "https://www.python.org/ftp/python/${PY_VER}/Python-${PY_VER}.tgz"
tar xzf python.tgz
cd Python-${PY_VER}
./configure --enable-optimizations
make -j $(nproc)
sudo -H make altinstall
curl -sS https://bootstrap.pypa.io/get-pip.py | sudo -H python3.12
cd ..
sudo rm -rf Python-${PY_VER} python.tgz

После выполнения всех этих действий у вас в системе будет установлена дополнительно еще одна версия Python. В данном случае это Python 3.13 а также инструмент pip тоже с версией 3.13. Системная версия Python изменена не будет и мы не рекомендуем ее изменять, так как некоторые системные компоненты могут быть зависимы от нее.

Чтобы использовать именно эту версию python и pip, вам нужно указывать целиком имена файлов, которые вы запускаете. Например:
python3.13 --version
pip3.13 --version

Теперь, чтобы создать виртуальное окружение для какого-либо модуля либо поллера, вам нужно использовать следующий синтаксис:
sudo python3.13 -m venv venv
sudo venv/bin/pip install -U pip wheel
и т.д.

Usm asterisk

2025-09-03T07:08:35Z

Uscld2:

[[Usm_asterisk_EN|en]] | [[Usm_asterisk|ru]]

'''USM_ASTERISK''' - модуль, взаимодействующий с Asterisk и обрабатывающий информацию о поступающих звонках абонентов

Данный модуль является заменой устаревшему win-модулю [[us_asteriskcall]]

'''[[Рекомендации по настройке системы Asterisk]]'''

== Общие данные ==

'''Язык модуля:''' Perl

'''Текущая версия:''' см. на странице: [[Модули]]

'''Минимальная версия Asterisk:''' 10.x

'''Статус модуля:''' [http://userside.ua/price.php Платный]

Необходимые модули Perl:
EV
Asterisk::AMI
Time::Local
LWP::UserAgent
HTTP::Request
FindBin

== Возможности ==

Для каждого пользователя указывается внутренний SIP-номер, который требуется контролировать. Например у пользователя на столе стоит аппаратный телефон, имеющий внутренний номер 5007 ''(либо программный телефон)''. Значит в учетной записи пользователя необходимо указать его номер 5007.

[[Файл:20150719_05.PNG|thumb|800px|center]]

При поступлении звонка на номер пользователя - в браузер будет выведена информация о входящем звонке. При этом если по входящему номеру будет выполнен поиск в базе абонентов и, при нахождении, выведена информация по абоненту.

[[Файл:20150719_04.PNG|thumb|375px|center]]

[[Файл:20150719_01.PNG|thumb|800px|center]]

Кроме абонентов выполняется поиск по телефонным номерам сотрудников

[[Файл:20150719_02.PNG|thumb|479px|center]]

Уведомления выводятся по очереди и во всех открытых вкладках САП "UserSide" у пользователя

[[Файл:20150719_03.PNG|thumb|373px|center]]

В разделе "Сообщения - Список звонков" можно просмотреть список всех звонков

[[Файл:20151129-145926.png|thumb|800px|center]]

Также в [[Карточка абонента|карточке абонента]] на вкладке "Тех.поддержка" видны все его звонки

[[Файл:2015_07_19_14_59_46.png|thumb|800px|center]]

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

== Настройка ==

'''Настройка Asterisk'''

В системе Asterisk для взаимодействия используется модуль Manager, который настраивается в файле ''/etc/asterisk/manager.conf''

В этом файле необходимо добавить блок настроек для пользователя, от имени которого будет происходить взаимодействие между Asterisk и usm_asterisk

Пример блока, который необходимо вписать в файл manager.conf

[userside]
secret = usm_asterisk_secret
deny = 0.0.0.0/0.0.0.0
permit = 192.168.1.2/255.255.255.255
read = all,system,call,log,verbose,command,agent,user,config
write = all,system,call,log,verbose,command,agent,user,config

Здесь:
userside — имя пользователя
usm_asterisk_secret — пароль
192.168.1.2 — адрес сервера, на котором функционирует модуль usm_asterisk

После выполнения этой команды необходимо войти в консоль asterisk и выполнить команду перезагрузки конфигурации

$ asterisk -r
> reload
> exit

'''Настройка UserSide'''

Убедитесь, что в конфигурационном файле ERP "UserSide" указан [[UserSide API Key|API-ключ]].

Далее этот ключ понадобится в файле настроек модуля usm_asterisk.

'''Настройка модуля usm_asterisk'''

1. Для работы модулю требуются модули perl: EV, Asterisk::AMI, Time::Local, LWP::UserAgent, HTTP::Request::Common, FindBin

2. В "UserSide" назначьте пользователям внутренние номера телефонов, при вызовах на которые должны отображаться уведомления

3. Создайте каталог, например, /opt/userside и скопируйте туда архив с модулем. Разархивируйте. Перейдите в каталог с разархивированным модулем.
<pre>
cd /opt/userside/uem_asterisk
</pre>

4. Скопируйте пример конфигурации usm_asterisk.conf.example с именем usm_asterisk.conf и настройте в нем следующее:

- Подключение к asterisk-manager
- Подключение к api UserSide
- Путь хранения логов, если нужно
- В переменой $zastertype укажите значение в соответствии с используемой версией Asterisk:
1 - Asterisk == 11 (AMI v1)
2 - Asterisk <= 10 (AMI v1)
3 - Asterisk >= 12 (AMI v2)
- Перечислите в значении переменой @zasterfromcontexts все транки, на которых необходима обработка входящих соединений.
Формат записи, например: ("from-gsm", "from-pstn", "from-external")

5. Скопируйте файл usm_asterisk.conf-supervisor в /etc/supervisor/conf.d/usm_asterisk.conf

6. Выполните тестовый запуск модуля:
<pre>
sudo perl usm_asterisk.pl
</pre>
Убедитесь, что нет ошибок. Если ошибок нет — остановите (Ctrl+C).

7. Перезапустите службу супервизора, чтобы он прочитал новую конфигурацию и перезапустил службы:
<pre>
sudo systemctl restart supervisor
</pre>

8. Убедитесь, что модуль работает (его состояние должно быть RUNNING):
<pre>
sudo supervisorctl status usm_asterisk
<pre>

9. Настройте демон newslog ''(/etc/newslog.conf)'' на ротацию логов модуля. Просто добавьте строку:

/var/log/usm_asterisk.* 644 10 200 * GJC

10. Проверьте работоспособность модуля, выполнив телефонный вызов. Контролировать работу модуля можно наблюдая за логами в реальном времени (путь указан для примере, путь к вашим логам зависит от параметра ps_logpath файла конфигурации usm_asterisk.conf):
<pre>
tail -f /var/log/usm_asterisk.log
</pre>

== Запуск в Docker-окружении ==

Если Вы используете USERSIDE в Docker-окружении, то вам наверняка будет интересно запускать в отдельных Docker-контейнерах и внешние модули usm.

Мы предоставляем docker-окружение для запуска модуля usm_asterisk (окружение не содержит файла модуля - его необходимо загрузить из личного кабинета самостоятельно).

Загрузить docker-окружение можно по ссылке: https://github.com/userside/usm_asterisk-docker-env/releases

== Действия, необходимые для проведения отладки работы модуля usm_asterisk ==

* Остановите модуль используя супервизор:
<pre>
sudo supervisorctl stop usm_asterisk
</pre>
* Измените в конфигурационном файле модуля usm_asterisk.conf параметры $ps_consolelog = 1, если необходимо выводить лог на экран, а не в файл, и/или, если необходимо выводить ответы API-сервера, $ps_apianswlog = 1
* Запустите модуль вручную при помощи следующей команды. При запуске модуль выведет информацию об этом на экран.
<pre>
perl usm_asterisk.pl
</pre>
* После окончания отладочных работ остановите работу модуля Ctrl+C, измените параметры $ps_consolelog и $ps_apianswlog, установив их в 0, запустите модуль используя супервизор:
<pre>
sudo supervisorctl start usm_asterisk
</pre>

'''Подключение к AMI Asterisk (для информации)'''

telnet 127.0.0.1 5038 | tee ami.log

Аутентификация (скопируйте текст и вставьте в сессию AMI, предварительно изменив имя и пароль):

Action: login
Username: admin
Secret: passwd1234

Дважды нажмите Enter

При правильном входе должны увидеть:

Response: Success Message: Authentication accepted

Выполните входящий вызов, который поступит на группу пользователей (Queue), после чего пользователь должен ответить и положить трубку.
После окончания работы с AMI выполните:

Action: logoff

Результат (файл ami.log) пришлите нам, предварительно заархивировав.

HOWTO: PostgreSQL version upgrade

2025-08-21T06:11:43Z

Uscld2:

[[HOWTO:_PostgreSQL_version_upgrade|en]] | [[HOWTO:_Обновление_версии_PostgreSQL|ru]]

This section describes the procedure for upgrading PostgreSQL ''between major versions'' (for example, from version 11 to version 17).

An upgrade within a version (for example, from version 17.1 to 17.2) ''happens automatically and does not require additional actions''.

'''We recommend that you familiarize yourself with the official upgrade instructions''' on the [https://www.postgresql.org/docs/current/upgrading.html postgresql.org] website.

In the Debian distribution and those based on it, there is a [https://packages.debian.org/sid/postgresql-common postgresql-common] package, which is installed automatically when the PostgreSQL package is installed. The postgresql-common package includes tools that simplify working with PostgreSQL database clusters, including upgrading DB clusters.

A database cluster ([https://www.postgresql.org/docs/current/glossary.html Database cluster]) in PostgreSQL refers to a server instance along with all the databases it serves, and not a distributed system as one might think.

The following example will show how to upgrade a DB cluster from version 11 to version 17 using the tools from the '''postgresql-common''' package.

== Upgrade procedure ==
# Stop USERSIDE.
# Upgrade the current version of the postgresql package within its major version (e.g., from 11.5 to 11.22).
# Upgrade the postgis package version to the latest version (e.g., from 2.5 to 3.3.4).
# Update the PostGIS extension in all databases of the cluster.
# Install the new version of the postgresql package without removing the old one (e.g., 17.1).
# Make a backup copy of the database and settings.
# Delete the DB cluster that was created automatically by the script during the new version installation.
# Perform the upgrade of the old version DB cluster to the new version cluster.
# Check if USERSIDE is working correctly.
# Delete the old version DB cluster, obsolete packages, and backup copies.

Set aside time for this operation. It can take quite a long time depending on the size of the database and the server's performance. Also, make sure you have enough free disk space, which will be needed for the cluster upgrade (at least as much as the current cluster occupies, but more is better).

[https://asciinema.org/a/do2AE0z30mg5JLIuI9zhGTPoR Watch the video instruction on asciinema].

== Step-by-step instructions ==
The SQL queries with the <code>SELECT</code> operator provided below are for reference to determine the currently installed versions.

=== Stop USERSIDE ===
<pre>
sudo supervisorctl stop all
sudo systemctl stop php8.3-fpm
</pre>
The PHP version is given as an example. Use the one that is used on your system.

Comment out the startup of all modules and userside in crontab. If you are using [[Usm_poller_(as_satellite)_EN|satellites]], stop the services on them as well.

=== Upgrade the current postgresql version within the major version ===
Check the current versions of the PostgreSQL and PostGIS system packages. Upgrade the currently installed versions of PostgreSQL and PostGIS to the latest versions within their major versions, and also, if the current version of PostGIS is below 3, additionally install the PostGIS 3 package for your version of PostgreSQL. If you already have PostGIS 3 installed, you only need to update it to the latest version.
<pre>
# get the postgresql version and the postgis extension version for the userside database
sudo -u postgres psql -A -t -c "SELECT VERSION()"
sudo -u postgres psql -d userside -A -t -c "SELECT PostGIS_full_version()"

# update the current package versions
sudo apt update
sudo apt install --only-upgrade -y postgresql-11 postgresql-11-postgis-2.5
# only if the current postgis version is lower than 3, additionally install postgis-3 for the current postgres version
sudo apt install -y postgresql-11-postgis-3
</pre>
Instead of 11 and 2.5, of course, specify the versions that are actually installed on your system.

=== Upgrade the postgis extension to the latest version ===
After updating the postgis package, you must accordingly update the postgis extension itself in the databases where this extension is present. You may have, for example, a copy of the userside database for testing - do not forget about it.
<pre>
sudo -u postgres psql -d userside -A -t -c "ALTER EXTENSION postgis UPDATE"
sudo -u postgres psql -d userside -A -t -c "SELECT PostGIS_full_version()"
</pre>
The second command will display the current version of the PostGIS extension after the update.

=== Upgrading from PostGIS 2.5 to PostGIS 3.x ===
If the previous <code>SELECT PostGIS_full_version()</code> query displays information like this:
<pre>
POSTGIS="3.3.4 3.3.4" [EXTENSION] . . .
. . .
[UNPACKAGED!] (raster procs from "2.5.5 r0" need upgrade)
</pre>
Then the following information is for you. Otherwise, skip this section.

There is some difference between PosGIS versions 2 and 3 that requires additional actions during the upgrade.
<pre>
# the same query twice
sudo -u postgres psql -d userside -A -t -c "SELECT postgis_extensions_upgrade()"
sudo -u postgres psql -d userside -A -t -c "SELECT postgis_extensions_upgrade()"
# remove the raster extension, which was previously part of the postgis extension
sudo -u postgres psql -d userside -A -t -c "DROP EXTENSION postgis_raster"
</pre>

=== Install new package versions ===
Also, remove the old postgis version 2 package if it was installed.
<pre>
sudo apt install -y postgresql-17 postgresql-17-postgis-3
sudo apt purge -y postgresql-11-postgis-2.5
</pre>

=== Make a backup copy of the database and configuration ===
The cluster migration tool does this absolutely safely, but extra caution will not be superfluous. Make temporary backup copies of the necessary databases and configuration, which can be safely deleted at the end of the update.
<pre>
sudo -u postgres pg_dump --no-acl -Fp -Z 5 userside --file=/backup/userside_emergency.sql.gz
sudo -u postgres pg_dump --no-acl -Fc userside --file=/backup/userside_emergency.dump
sudo tar czf /backup/postgres_config_emergency.tgz -C /etc/postgresql/11/main .
</pre>
The /backup directory must exist and must be writable by all users.

=== Delete the automatically created DB cluster ===
Using the <code>pg_lsclusters</code> utility from postgresql-common, see what your DB clusters look like:
<pre>
sudo pg_lsclusters
</pre>
The command output will be approximately as follows:
<pre>
Ver Cluster Port Status Owner Data directory Log file
11 main 5432 online postgres /var/lib/postgresql/11/main /var/log/postgresql/postgresql-11.log
17 main 5433 online postgres /var/lib/postgresql/17/main /var/log/postgresql/postgresql-17.log
</pre>
The 17/main cluster was created automatically by the postgresql installation script and uses the new port 5433. It needs to be stopped and deleted — it is not needed, as a cluster migration procedure will be performed, which will create a new cluster automatically.
<pre>
sudo pg_dropcluster 17 main --stop
</pre>
Running the <code>pg_lsclusters</code> command again should show that you have one cluster left, '''11/main'''.

=== Perform the upgrade of the old version DB cluster to the new version cluster ===
Stop the postgresql service
<pre>
sudo systemctl stop postgresql
</pre>
Start the DB cluster '''11/main''' upgrade process using the <code>pg_upgradecluster</code> utility from the postgresql-common package. This action may take a lot of time and disk space.
<pre>
sudo pg_upgradecluster 11 main
</pre>
After the upgrade operation is complete, you will see the new state of the clusters (the old version should be in '''down''' mode and port 5432 is now assigned to the new cluster '''17/main'''):
<pre>
Ver Cluster Port Status Owner Data directory Log file
11 main 5433 down postgres /var/lib/postgresql/11/main /var/log/postgresql/postgresql-11.log
17 main 5432 online postgres /var/lib/postgresql/17/main /var/log/postgresql/postgresql-17.log
</pre>
Start the postgres service
<pre>
sudo systemctl start postgresql
</pre>

=== Check USERSIDE operation ===
First, run the commands that display the versions to make sure that the database is now running on the new version DB cluster:
<pre>
sudo -u postgres psql -A -t -c "SELECT VERSION()"
sudo -u postgres psql -d userside -A -t -c "SELECT PostGIS_full_version()"
</pre>
You should see postgresql version 17 and postgis version 3.x.x.

Now start the FPM service and go to USERSIDE through a browser.
<pre>
sudo systemctl start php8.3-fpm
</pre>
Since other services are stopped, you will probably see errors related to them, but the USERSIDE interface should open without database connection errors.
If everything is successful, then uncomment the previously commented lines in crontab and start the external services managed by supervisor, including on the satellite:
<pre>
sudo supervisorctl start all
sudo supervisorctl status
</pre>

=== Cleanup after a successful upgrade ===
If USERSIDE is working correctly and there are no database interaction errors, you can delete the old cluster and packages. You can also, if you wish, delete the emergency backups or wait a few days to be absolutely sure they will not be needed.
<pre>
sudo pg_dropcluster 11 main --stop
sudo apt purge -y postgresql-11 postgresql-11-postgis-3
sudo apt autoremove -y
sudo rm /backup/userside_emergency* /backup/postgres_config_emergency.tgz
sudo rm -rf /var/lib/postgresql/11/main
</pre>

HOWTO: Обновление версии PostgreSQL

2025-08-21T06:07:32Z

Uscld2:

[[HOWTO:_PostgreSQL_version_upgrade|en]] | [[HOWTO:_Обновление_версии_PostgreSQL|ru]]

В данном разделе описана процедура обновления PostgreSQL ''между основными версиями'' (например, с версии 11 на версию 17).

Обновление внутри версии (например, с версии 17.1 на версию 17.2) ''происходит автоматически и не требует дополнительных действий''.

'''Рекомендуем ознакомиться с официальными инструкциями по обновлению''' на сайте [https://www.postgresql.org/docs/current/upgrading.html postgresql.org].

В дистрибутиве Debian и основанных на нем существует пакет [https://packages.debian.org/sid/postgresql-common postgresql-common], устанавливаемый автоматически при установке пакета PostgreSQL. В состав postgresql-common входят инструменты, упрощающие работу с кластерами баз данных PostgreSQL. В том числе и обновление кластеров БД.

Кластером баз данных ([https://www.postgresql.org/docs/current/glossary.html Database cluster]) в PostgreSQL называется экземпляр сервера вместе со всеми обслуживаемыми БД, а не распределенную систему, как может показаться.

В следующем примере будет показано обновление кластера БД с версии 11 на версию 17 используя инструменты из пакета '''postgresql-common'''.

== Порядок обновления ==
# Остановить USERSIDE.
# Обновить текущую версию пакета postgresql в пределах основной версии (например, с 11.5 до 11.22).
# Обновить версию пакета postgis до самой последней версии (например, с 2.5 до 3.3.4).
# Обновить расширение PostGIS во всех базах данных кластера.
# Установить новую версию пакета postgresql не удаляя старой (например 17.1)
# Сделать запасную резервную копию базы данных и настроек
# Удалить кластер БД, созданный автоматически сценарием при установке новой версии
# Выполнить обновление кластера БД старой версии до кластера новой версии
# Проверить работу USERSIDE
# Удалить кластер БД старой версии, устаревшие пакеты и запасные резервные копии

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

[https://asciinema.org/a/do2AE0z30mg5JLIuI9zhGTPoR Посмотреть видеоинструкцию на asciinema].

== Пошаговая инструкция ==
SQL-запросы с оператором <code>SELECT</code>, приведенные далее, необходимы для определения текущих установленных версий в качестве справочной информации.

=== Остановить USERSIDE ===
<pre>
sudo supervisorctl stop all
sudo systemctl stop php8.3-fpm
</pre>
Версия php указана для примера. Используйте ту, что испльзуется у вас.

Закомментируйте запуск всех модулей и userside в crontab. Если используете [[Usm_poller_(as_satellite)|сателлиты]], остановите службы и на них.

=== Обновить текущую версии postgresql в пределах основной версии ===
Проверить текущие версии системных пакетов PostgreSQL и PostGIS. Обновить текущие установленные версии PostgreSQL и PostGIS до посладних версий в пределах их основных версий, а также, если текущая версия PostGIS ниже 3, установить дополнительно пакет PostGIS 3 для вашей версии PostgreSQL. Если у вас уже сейчас установлен PostGIS 3, то вам нужно только лишь его обновить до последней версии.
<pre>
# получить версию postgresql и версию расширения postgis для базы данных userside
sudo -u postgres psql -A -t -c "SELECT VERSION()"
sudo -u postgres psql -d userside -A -t -c "SELECT PostGIS_full_version()"

# обновить такущие версии пакетов
sudo apt update
sudo apt install --only-upgrade -y postgresql-11 postgresql-11-postgis-2.5
# только если текущая версия postgis ниже 3, дополнительно установить postgis-3 для текущей версии postgres
sudo apt install -y postgresql-11-postgis-3
</pre>
Вместо 11 и 2.5, конечно же, укажите те версии, которе фактически установлены у вас.

=== Обновить расширение postgis до самой последней версии ===
После обновления пакета postgis необходимо соответственно обновить и само расширение postgis в базах данных, где это расширение присутствует. У вас может быть, например, копия базы данных userside для тестов - не забудьте про нее.
<pre>
sudo -u postgres psql -d userside -A -t -c "ALTER EXTENSION postgis UPDATE"
sudo -u postgres psql -d userside -A -t -c "SELECT PostGIS_full_version()"
</pre>
Вторая команда отобразит текущую версию расширения PostGIS после обновления.

=== Обновление с PostGIS 2.5 на PostGIS 3.x ===
Если предыдущий запрос <code>SELECT PostGIS_full_version()</code> отображает информацию подобно такой:
<pre>
POSTGIS="3.3.4 3.3.4" [EXTENSION] . . .
. . .
[UNPACKAGED!] (raster procs from "2.5.5 r0" need upgrade)
</pre>
То следующая информация для вас. Иначе пропустите этот раздел.

Между версиям PosGIS 2 и 3 существует некоторая разница, которая требует дополнительных действий при обновлении.
<pre>
# дважды один и тот же запрос
sudo -u postgres psql -d userside -A -t -c "SELECT postgis_extensions_upgrade()"
sudo -u postgres psql -d userside -A -t -c "SELECT postgis_extensions_upgrade()"
# удалить расширение raster, которое раньше было частью расширения postgis
sudo -u postgres psql -d userside -A -t -c "DROP EXTENSION postgis_raster"
</pre>

=== Установить новые версии пакетов ===
Также удалить старый пакет postgis версии 2, если он был установлен.
<pre>
sudo apt install -y postgresql-17 postgresql-17-postgis-3
sudo apt purge -y postgresql-11-postgis-2.5
</pre>

=== Сделать запасную резервную копию базы данных и конфигурации ===
Инструмент миграции кластеров делает это абсолютно безопасно, однако дополнительная осторожность лишней не будет. Сделайте запасные временные резервные копии нужных баз данных и конфигурации, которые в конце обновления можно будет смело удалить.
<pre>
sudo -u postgres pg_dump --no-acl -Fp -Z 5 userside --file=/backup/userside_emergency.sql.gz
sudo -u postgres pg_dump --no-acl -Fc userside --file=/backup/userside_emergency.dump
sudo tar czf /backup/postgres_config_emergency.tgz -C /etc/postgresql/11/main .
</pre>
Каталог /backup должен существовать и должен быть доступен для записи всем пользователям.

=== Удалить автоматически созданный кластер БД ===
При помощи утилиты <code>pg_lsclusters</code> из postgresql-common посмотрите, как выглядят ваши кластеры БД:
<pre>
sudo pg_lsclusters
</pre>
Вывод команды будет примерно следующим:
<pre>
Ver Cluster Port Status Owner Data directory Log file
11 main 5432 online postgres /var/lib/postgresql/11/main /var/log/postgresql/postgresql-11.log
17 main 5433 online postgres /var/lib/postgresql/17/main /var/log/postgresql/postgresql-17.log
</pre>
Кластер 17/main был создан автоматически сценарием установки postgresql и использует новый порт 5433. Его нужно остановить и удалить — он не нужен, т.к. будет выполняться процедура миграции кластера, которая создаст новый кластер автоматически.
<pre>
sudo pg_dropcluster 17 main --stop
</pre>
Повторное выполнение команды <code>pg_lsclusters</code> должно показать, что у вас остался один кластер '''11/main'''.

=== Выполнить обновление кластера БД старой версии до кластера новой версии ===
Остановите службу postgresql
<pre>
sudo systemctl stop postgresql
</pre>
Запустите процесс обновления кластера БД '''11/main''' используя утилиту <code>pg_upgradecluster</code> из пакета postgresql-common. Это действие может занять много времени и дискового пространства.
<pre>
sudo pg_upgradecluster 11 main
</pre>
После завершения операции обновления вы увидите новое состояние кластеров (старая версия должна находиться в режиме '''down''' и порт 5432 теперь назначен новому кластеру '''17/main'''):
<pre>
Ver Cluster Port Status Owner Data directory Log file
11 main 5433 down postgres /var/lib/postgresql/11/main /var/log/postgresql/postgresql-11.log
17 main 5432 online postgres /var/lib/postgresql/17/main /var/log/postgresql/postgresql-17.log
</pre>
Запустите службу postgres
<pre>
sudo systemctl start postgresql
</pre>

=== Проверить работу USERSIDE ===
Сначала выполните команды, отображающие версии, чтобы убедиться что база данных теперь работает на кластере БД новой версии:
<pre>
sudo -u postgres psql -A -t -c "SELECT VERSION()"
sudo -u postgres psql -d userside -A -t -c "SELECT PostGIS_full_version()"
</pre>
Вы должны увидеть 17ю версию postgresql и 3.x.x версию postgis.

Теперь запустите службу FPM и зайдите в USERSIDE через браузер.
<pre>
sudo systemctl start php8.3-fpm
</pre>
Так как другие службы остановлены, вы, вероятно, увидите ошибки связанные с ними, но при этом интерфейс USERSIDE должен открыться без ошибок подключения к базе данных.
Если все успешно, то раскомментируйте закомментированные ранее строки в crontab и запустите внешние службы, находящиеся под управлением supervisor, в том числе на сателлите:
<pre>
sudo supervisorctl start all
sudo supervisorctl status
</pre>

=== Очистка после успешного обновления ===
Если USERSIDE работает корректно, ошибок взаимодействия с БД нет, то можно удалить старый кластер и пакеты. Вы также, по желанию, можете удалить аварийные резервные копии или подождать несколько дней, чтобы точно убедиться, что они не пригодятся.
<pre>
sudo pg_dropcluster 11 main --stop
sudo apt purge -y postgresql-11 postgresql-11-postgis-3
sudo apt autoremove -y
sudo rm /backup/userside_emergency* /backup/postgres_config_emergency.tgz
sudo rm -rf /var/lib/postgresql/11/main
</pre>

HOWTO: Обновление версии PostgreSQL

2025-08-21T06:01:41Z

Uscld2:

[[HOWTO:_PostgreSQL_version_upgrade|en]] | [[HOWTO:_Обновление_версии_PostgreSQL|ru]]

В данном разделе описана процедура обновления PostgreSQL ''между основными версиями'' (например, с версии 11 на версию 17).

Обновление внутри версии (например, с версии 17.1 на версию 17.2) ''происходит автоматически и не требует дополнительных действий''.

'''Рекомендуем ознакомиться с официальными инструкциями по обновлению''' на сайте [https://www.postgresql.org/docs/current/upgrading.html postgresql.org].

В дистрибутиве Debian и основанных на нем существует пакет [https://packages.debian.org/sid/postgresql-common postgresql-common], устанавливаемый автоматически при установке пакета PostgreSQL. В состав postgresql-common входят инструменты, упрощающие работу с кластерами баз данных PostgreSQL. В том числе и обновление кластеров БД.

Кластером баз данных ([https://www.postgresql.org/docs/current/glossary.html Database cluster]) в PostgreSQL называется экземпляр сервера вместе со всеми обслуживаемыми БД, а не распределенную систему, как может показаться.

В следующем примере будет показано обновление кластера БД с версии 11 на версию 17 используя инструменты из пакета '''postgresql-common'''.

== Порядок обновления ==
# Остановить USERSIDE.
# Обновить текущую версию пакета postgresql в пределах основной версии (например, с 11.5 до 11.22).
# Обновить версию пакета postgis до самой последней версии (например, с 2.5 до 3.3.4).
# Обновить расширение PostGIS во всех базах данных кластера.
# Установить новую версию пакета postgresql не удаляя старой (например 17.1)
# Сделать запасную резервную копию базы данных и настроек
# Удалить кластер БД, созданный автоматически сценарием при установке новой версии
# Выполнить обновление кластера БД старой версии до кластера новой версии
# Проверить работу USERSIDE
# Удалить кластер БД старой версии, устаревшие пакеты и запасные резервные копии

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

[https://asciinema.org/a/do2AE0z30mg5JLIuI9zhGTPoR Посмотреть видеоинструкцию на asciinema].

== Пошаговая инструкция ==
SQL-запросы с оператором <code>SELECT</code>, приведенные далее, необходимы для определения текущих установленных версий в качестве справочной информации.

=== Остановить USERSIDE ===
<pre>
sudo supervisorctl stop all
sudo systemctl stop php8.3-fpm
</pre>
Версия php указана для примера. Используйте ту, что испльзуется у вас.

Закомментируйте запуск всех модулей и userside в crontab. Если используете [[Usm_poller_(as_satellite)|сателлиты]], остановите службы и на них.

=== Обновить текущую версии postgresql в пределах основной версии ===
Проверить текущие версии системных пакетов PostgreSQL и PostGIS. Обновить текущие установленные версии PostgreSQL и PostGIS до посладних версий в пределах их основных версий, а также, если текущая версия PostGIS ниже 3, установить дополнительно пакет PostGIS 3 для вашей версии PostgreSQL. Если у вас уже сейчас установлен PostGIS 3, то вам нужно только лишь его обновить до последней версии.
<pre>
# получить версию postgresql и версию расширения postgis для базы данных userside
sudo -u postgres psql -A -t -c "SELECT VERSION()"
sudo -u postgres psql -d userside -A -t -c "SELECT PostGIS_full_version()"

# обновить такущие версии пакетов
sudo apt update
sudo apt install --only-upgrade -y postgresql-11 postgresql-11-postgis-2.5
# только если текущая версия postgis ниже 3, дополнительно установить postgis-3 для текущей версии postgres
sudo apt install -y postgresql-11-postgis-3
</pre>
Вместо 11 и 2.5, конечно же, укажите те версии, которе фактически установлены у вас.

=== Обновить расширение postgis до самой последней версии ===
После обновления пакета postgis необходимо соответственно обновить и само расширение postgis в базах данных, где это расширение присутствует. У вас может быть, например, копия базы данных userside для тестов - не забудьте про нее.
<pre>
sudo -u postgres psql -d userside -A -t -c "ALTER EXTENSION postgis UPDATE"
sudo -u postgres psql -d userside -A -t -c "SELECT PostGIS_full_version()"
</pre>
Вторая команда отобразит текущую версию расширения PostGIS после обновления.

=== Обновление с PostGIS 2.5 на PostGIS 3.x ===
Если предыдущий запрос <code>SELECT PostGIS_full_version()</code> отображает информацию подобно такой:
<pre>
POSTGIS="3.3.4 3.3.4" [EXTENSION] . . .
. . .
[UNPACKAGED!] (raster procs from "2.5.5 r0" need upgrade)
</pre>
То следующая информация для вас. Иначе пропустите этот раздел.

Между версиям PosGIS 2 и 3 существует некоторая разница, которая требует дополнительных действий при обновлении.
<pre>
# дважды один и тот же запрос
sudo -u postgres psql -d postgres -A -t -c "SELECT postgis_extensions_upgrade()"
sudo -u postgres psql -d postgres -A -t -c "SELECT postgis_extensions_upgrade()"
# удалить расширение raster, которое раньше было частью расширения postgis
sudo -u postgres psql -d postgres -A -t -c "DROP EXTENSION postgis_raster"
</pre>

=== Установить новые версии пакетов ===
Также удалить старый пакет postgis версии 2, если он был установлен.
<pre>
sudo apt install -y postgresql-17 postgresql-17-postgis-3
sudo apt purge -y postgresql-11-postgis-2.5
</pre>

=== Сделать запасную резервную копию базы данных и конфигурации ===
Инструмент миграции кластеров делает это абсолютно безопасно, однако дополнительная осторожность лишней не будет. Сделайте запасные временные резервные копии нужных баз данных и конфигурации, которые в конце обновления можно будет смело удалить.
<pre>
sudo -u postgres pg_dump --no-acl -Fp -Z 5 userside --file=/backup/userside_emergency.sql.gz
sudo -u postgres pg_dump --no-acl -Fc userside --file=/backup/userside_emergency.dump
sudo tar czf /backup/postgres_config_emergency.tgz -C /etc/postgresql/11/main .
</pre>
Каталог /backup должен существовать и должен быть доступен для записи всем пользователям.

=== Удалить автоматически созданный кластер БД ===
При помощи утилиты <code>pg_lsclusters</code> из postgresql-common посмотрите, как выглядят ваши кластеры БД:
<pre>
sudo pg_lsclusters
</pre>
Вывод команды будет примерно следующим:
<pre>
Ver Cluster Port Status Owner Data directory Log file
11 main 5432 online postgres /var/lib/postgresql/11/main /var/log/postgresql/postgresql-11.log
17 main 5433 online postgres /var/lib/postgresql/17/main /var/log/postgresql/postgresql-17.log
</pre>
Кластер 17/main был создан автоматически сценарием установки postgresql и использует новый порт 5433. Его нужно остановить и удалить — он не нужен, т.к. будет выполняться процедура миграции кластера, которая создаст новый кластер автоматически.
<pre>
sudo pg_dropcluster 17 main --stop
</pre>
Повторное выполнение команды <code>pg_lsclusters</code> должно показать, что у вас остался один кластер '''11/main'''.

=== Выполнить обновление кластера БД старой версии до кластера новой версии ===
Остановите службу postgresql
<pre>
sudo systemctl stop postgresql
</pre>
Запустите процесс обновления кластера БД '''11/main''' используя утилиту <code>pg_upgradecluster</code> из пакета postgresql-common. Это действие может занять много времени и дискового пространства.
<pre>
sudo pg_upgradecluster 11 main
</pre>
После завершения операции обновления вы увидите новое состояние кластеров (старая версия должна находиться в режиме '''down''' и порт 5432 теперь назначен новому кластеру '''17/main'''):
<pre>
Ver Cluster Port Status Owner Data directory Log file
11 main 5433 down postgres /var/lib/postgresql/11/main /var/log/postgresql/postgresql-11.log
17 main 5432 online postgres /var/lib/postgresql/17/main /var/log/postgresql/postgresql-17.log
</pre>
Запустите службу postgres
<pre>
sudo systemctl start postgresql
</pre>

=== Проверить работу USERSIDE ===
Сначала выполните команды, отображающие версии, чтобы убедиться что база данных теперь работает на кластере БД новой версии:
<pre>
sudo -u postgres psql -A -t -c "SELECT VERSION()"
sudo -u postgres psql -d userside -A -t -c "SELECT PostGIS_full_version()"
</pre>
Вы должны увидеть 17ю версию postgresql и 3.x.x версию postgis.

Теперь запустите службу FPM и зайдите в USERSIDE через браузер.
<pre>
sudo systemctl start php8.3-fpm
</pre>
Так как другие службы остановлены, вы, вероятно, увидите ошибки связанные с ними, но при этом интерфейс USERSIDE должен открыться без ошибок подключения к базе данных.
Если все успешно, то раскомментируйте закомментированные ранее строки в crontab и запустите внешние службы, находящиеся под управлением supervisor, в том числе на сателлите:
<pre>
sudo supervisorctl start all
sudo supervisorctl status
</pre>

=== Очистка после успешного обновления ===
Если USERSIDE работает корректно, ошибок взаимодействия с БД нет, то можно удалить старый кластер и пакеты. Вы также, по желанию, можете удалить аварийные резервные копии или подождать несколько дней, чтобы точно убедиться, что они не пригодятся.
<pre>
sudo pg_dropcluster 11 main --stop
sudo apt purge -y postgresql-11 postgresql-11-postgis-3
sudo apt autoremove -y
sudo rm /backup/userside_emergency* /backup/postgres_config_emergency.tgz
sudo rm -rf /var/lib/postgresql/11/main
</pre>

HOWTO: Обновление версии PostgreSQL

2025-08-20T18:13:38Z

Uscld2:

[[HOWTO:_PostgreSQL_version_upgrade|en]] | [[HOWTO:_Обновление_версии_PostgreSQL|ru]]

В данном разделе описана процедура обновления PostgreSQL ''между основными версиями'' (например, с версии 11 на версию 17).

Обновление внутри версии (например, с версии 17.1 на версию 17.2) ''происходит автоматически и не требует дополнительных действий''.

'''Рекомендуем ознакомиться с официальными инструкциями по обновлению''' на сайте [https://www.postgresql.org/docs/current/upgrading.html postgresql.org].

В дистрибутиве Debian и основанных на нем существует пакет [https://packages.debian.org/sid/postgresql-common postgresql-common], устанавливаемый автоматически при установке пакета PostgreSQL. В состав postgresql-common входят инструменты, упрощающие работу с кластерами баз данных PostgreSQL. В том числе и обновление кластеров БД.

Кластером баз данных ([https://www.postgresql.org/docs/current/glossary.html Database cluster]) в PostgreSQL называется экземпляр сервера вместе со всеми обслуживаемыми БД, а не распределенную систему, как может показаться.

В следующем примере будет показано обновление кластера БД с версии 11 на версию 17 используя инструменты из пакета '''postgresql-common'''.

== Порядок обновления ==
# Остановить USERSIDE.
# Обновить текущую версии postgresql в пределах основной версии (например, с 11.5 до 11.22).
# Обновить расширение postgis до самой последней версии (например, с 2.5 до 3.3.4). Также обязательно обновить расширение и в самой базе данных.
# Установить новую версию postgresql не удаляя старой (например 17.1)
# Сделать запасную резервную копию базы данных и настроек
# Удалить кластер БД, созданный автоматически сценарием при установке новой версии
# Выполнить обновление кластера БД старой версии до кластера новой версии
# Проверить работу USERSIDE
# Удалить кластер БД старой версии, устаревшие пакеты и запасные резервные копии

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

[https://asciinema.org/a/do2AE0z30mg5JLIuI9zhGTPoR Посмотреть видеоинструкцию на asciinema].

== Пошаговая инструкция ==
SQL-запросы с оператором <code>SELECT</code>, приведенные далее, необходимы для определения текущих установленных версий в качестве справочной информации.

=== Остановить USERSIDE ===
<pre>
sudo supervisorctl stop all
sudo systemctl stop php8.3-fpm
</pre>
Версия php указана для примера. Используйте ту, что испльзуется у вас.

Закомментируйте запуск всех модулей и userside в crontab.

=== Обновить текущую версии postgresql в пределах основной версии ===
Проверить текущие версии системных пакетов PostgreSQL и PostGIS. Обновить текущие установленные версии PostgreSQL и PostGIS до посладних версий, а также, если текущая версия PostGIS ниже 3, установить дополнительно пакет PostGIS 3 для вашей версии PostgreSQL. Если у вас уже сейчас установлен PostGIS 3, то вам нужно только лишь его обновить до последней версии.
<pre>
sudo -u postgres psql -d userside -A -t -c "SELECT VERSION()"
sudo -u postgres psql -d userside -A -t -c "SELECT PostGIS_full_version()"

sudo apt update
sudo apt install --only-upgrade -y postgresql-11 postgresql-11-postgis-2.5
# только если текущая версия postgis ниже 3
sudo apt install -y postgresql-11-postgis-3
</pre>
Вместо 11 и 2.5 укажите те версии, которе фактически установлены у вас.

=== Обновить расширение postgis до самой последней версии ===
Обязательно также обновить расширение postgis в самих базах данных! У вас может быть несколько баз данных, в которые установлено это расширение. Например, у вас на сервре есть еще тестовая база данных (копия основной для тестов). Проверьте все существующие базы данных сервера на наличие расширения PostGIS и обновите его в каждой базе данных. Вы можете просто попытаться обновить расширение во всех базах данных, там где его нет — будет просто ошибка обновления. Далее показано как обновить в базе данных userisde. Проделайте это для всех баз данных, в которые оно установлено.
<pre>
sudo -u postgres psql -d userside -A -t -c "ALTER EXTENSION postgis UPDATE"
sudo -u postgres psql -d userside -A -t -c "SELECT PostGIS_full_version()"
</pre>

=== Обновление с PostGIS 2.5 на PostGIS 3.x ===
Если предыдущий запрос <code>SELECT PostGIS_full_version()</code> отображает информацию подобно такой:
<pre>
POSTGIS="3.3.4 3.3.4" [EXTENSION] . . .
. . .
[UNPACKAGED!] (raster procs from "2.5.5 r0" need upgrade)
</pre>
То следующая информация для вас.

Между версиям PosGIS 2 и 3 существует некоторая разница, которая требует дополнительных действий при обновлении. Если вы после выполнения предыдущего запроса не увидели такой проблем, то следующие действия выполнять не нужно — переходите к следующему разделу.
<pre>
# дважды один и тот же запрос
sudo -u postgres psql -d postgres -A -t -c "SELECT postgis_extensions_upgrade()"
sudo -u postgres psql -d postgres -A -t -c "SELECT postgis_extensions_upgrade()"
sudo -u postgres psql -d postgres -A -t -c "DROP EXTENSION postgis_raster"
</pre>

=== Установить новые версии пакетов ===
А также удалить старый пакет postgis версии 2, если он был.
<pre>
sudo apt install -y postgresql-17 postgresql-17-postgis-3
sudo apt purge postgresql-11-postgis-2.5
</pre>

=== Сделать запасную резервную копию базы данных и настроек ===
Инструмент миграции кластеров между версиями делает это абсолютно безопасно, однако дополнительная осторожность лишней не будет. Сделайте запасные временные резервные копии, которые в конце обновления можно будет удалить.
<pre>
sudo -u postgres pg_dump --no-acl -Fp -Z 5 userside --file=/backup/userside_emergency.sql.gz
sudo -u postgres pg_dump --no-acl -Fc userside --file=/backup/userside_emergency.dump
sudo tar czf /backup/postgres_config_emergency.tgz -C /etc/postgresql/11/main .
</pre>
Каталог /backup должен существовать и должен быть доступен для записи всем пользователям.

=== Удалить кластер БД, созданный автоматически сценарием при установке новой версии ===
При помощи утилиты <code>pg_lsclusters</code> из postgresql-common посмотрите, как выглядят ваши кластеры БД:
<pre>
sudo pg_lsclusters
</pre>
Вывод команды будет примерно следующим:
<pre>
Ver Cluster Port Status Owner Data directory Log file
11 main 5432 online postgres /var/lib/postgresql/11/main /var/log/postgresql/postgresql-11.log
17 main 5433 online postgres /var/lib/postgresql/17/main /var/log/postgresql/postgresql-17.log
</pre>
Кластер 17/main был создан автоматически сценарием установки postgresql и использует новый порт 5433. Его нужно остановить и удалить — он не нужен, т.к. будет выполняться процедура миграции кластера, которая создаст новый кластер автоматически.
<pre>
sudo pg_dropcluster 17 main --stop
</pre>
Повторное выполнение команды <code>pg_lsclusters</code> должно показать, что у вас остался один кластер '''11/main'''.

=== Выполнить обновление кластера БД старой версии до кластера новой версии ===
Остановите службу postgresql
<pre>
sudo systemctl stop postgresql
</pre>
Запустите процесс обновления кластера БД '''11/main''' используя утилиту <code>pg_upgradecluster</code> из пакета postgresql-common. Это действие может занять много времени и дискового пространства.
<pre>
sudo pg_upgradecluster 11 main
</pre>
После завершения операции обновления вы увидите новое состояние кластеров (старая версия должна находиться в режиме '''down''' и порт 5432 теперь используется новым кластером):
<pre>
Ver Cluster Port Status Owner Data directory Log file
11 main 5433 down postgres /var/lib/postgresql/11/main /var/log/postgresql/postgresql-11.log
17 main 5432 online postgres /var/lib/postgresql/17/main /var/log/postgresql/postgresql-17.log
</pre>
Запустите службу postgres
<pre>
sudo systemctl start postgresql
</pre>

=== Проверить работу USERSIDE ===
Сначала выполните команды, отображающие версии, чтобы убедиться что база данных теперь работает на кластере БД новой версии:
<pre>
sudo -u postgres psql -d userside -A -t -c "SELECT VERSION()"
sudo -u postgres psql -d userside -A -t -c "SELECT PostGIS_full_version()"
</pre>
Вы должны увидеть 17ю версию postgresql и 3.x.x версию postgis.

Теперь запустите службу FPM и зайдите в USERSIDE через браузер.
<pre>
sudo systemctl start php8.3-fpm
</pre>
Так как другие службы остановлены, вы, вероятно, увидите ошибки связанные с ними, но при этом интерфейс USERSIDE должен открыться без ошибок подключения к базе данных.
Если все успешно, то раскомментируйте закомментированные ранее строки в crontab и запустите внешние службы, находящиеся под управлением supervisor:
<pre>
sudo supervisorctl start all
sudo supervisorctl status
</pre>

=== Удалить кластер БД старой версии, устаревшие пакеты и запасные резервные копии ===
Если USERSIDE работает корректно, ошибок взаимодействия с БД нет, то можно удалить старый кластер и пакеты. Вы также, по желанию, можете удалить аварийные резервные копии или подождать несколько дней, чтобы точно убедиться, что они не пригодятся.
<pre>
sudo pg_dropcluster 11 main --stop
sudo apt purge -y postgresql-11 postgresql-11-postgis-3
sudo apt autoremove -y
sudo rm /backup/userside_emergency* /backup/postgres_config_emergency.tgz
sudo rm -rf /var/lib/postgresql/11/main
</pre>

HOWTO: Обновление версии PostgreSQL

2025-08-20T18:13:14Z

Uscld2:

[[HOWTO:_PostgreSQL_version_upgrade|en]] | [[HOWTO:_Обновление_версии_PostgreSQL|ru]]

В данном разделе описана процедура обновления PostgreSQL ''между основными версиями'' (например, с версии 11 на версию 17).

Обновление внутри версии (например, с версии 17.1 на версию 17.2) ''происходит автоматически и не требует дополнительных действий''.

'''Рекомендуем ознакомиться с официальными инструкциями по обновлению''' на сайте [https://www.postgresql.org/docs/current/upgrading.html postgresql.org].

В дистрибутиве Debian и основанных на нем существует пакет [https://packages.debian.org/sid/postgresql-common postgresql-common], устанавливаемый автоматически при установке пакета PostgreSQL. В состав postgresql-common входят инструменты, упрощающие работу с кластерами баз данных PostgreSQL. В том числе и обновление кластеров БД.

Кластером баз данных ([https://www.postgresql.org/docs/current/glossary.html Database cluster]) в PostgreSQL называется экземпляр сервера вместе со всеми обслуживаемыми БД, а не распределенную систему, как может показаться.

В следующем примере будет показано обновление кластера БД с версии 11 на версию 17 используя инструменты из пакета '''postgresql-common'''.

== Порядок обновления ==
# Остановить USERSIDE.
# Обновить текущую версии postgresql в пределах основной версии (например, с 11.5 до 11.22).
# Обновить расширение postgis до самой последней версии (например, с 2.5 до 3.3.4). Также обязательно обновить расширение и в самой базе данных.
# Установить новую версию postgresql не удаляя старой (например 17.1)
# Сделать запасную резервную копию базы данных и настроек
# Удалить кластер БД, созданный автоматически сценарием при установке новой версии
# Выполнить обновление кластера БД старой версии до кластера новой версии
# Проверить работу USERSIDE
# Удалить кластер БД старой версии, устаревшие пакеты и запасные резервные копии

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

[https://asciinema.org/a/do2AE0z30mg5JLIuI9zhGTPoR Посмотреть видеоинструкцию на asciinema].

== Пошаговая инструкция ==
SQL-запросы с оператором <code>SELECT</code>, приведенные далее, необходимы для определения текущих установленных версий в качестве справочной информации.

=== Остановить USERSIDE ===
<pre>
sudo supervisorctl stop all
sudo systemctl stop php8.3-fpm
</pre>
Версия php указана для примера. Используйте ту, что испльзуется у вас.

Закомментируйте запуск всех модулей и userside в crontab.

=== Обновить текущую версии postgresql в пределах основной версии ===
Проверить текущие версии системных пакетов PostgreSQL и PostGIS. Обновить текущие установленные версии PostgreSQL и PostGIS до посладних версий, а также, если текущая версия PostGIS ниже 3, установить дополнительно пакет PostGIS 3 для вашей версии PostgreSQL. Если у вас уже сейчас установлен PostGIS 3, то вам нужно только лишь его обновить до последней версии.
<pre>
sudo -u postgres psql -d userside -A -t -c "SELECT VERSION()"
sudo -u postgres psql -d userside -A -t -c "SELECT PostGIS_full_version()"

sudo apt update
sudo apt install --only-upgrade -y postgresql-11 postgresql-11-postgis-2.5
# только если текущая версия postgis ниже 3
sudo apt install -y postgresql-11-postgis-3
</pre>
Вместо 11 и 2.5 укажите те версии, которе фактически установлены у вас.

=== Обновить расширение postgis до самой последней версии ===
Обязательно также обновить расширение postgis в самих базах данных! У вас может быть несколько баз данных, в которые установлено это расширение. Например, у вас на сервре есть еще тестовая база данных (копия основной для тестов). Проверьте все существующие базы данных сервера на наличие расширения PostGIS и обновите его в каждой базе данных. Вы можете просто попытаться обновить расширение во всех базах данных, там где его нет — будет просто ошибка обновления. Далее показано как обновить в базе данных userisde. Проделайте это для всех баз данных, в которые оно установлено.
<pre>
sudo -u postgres psql -d userside -A -t -c "ALTER EXTENSION postgis UPDATE"
sudo -u postgres psql -d userside -A -t -c "SELECT PostGIS_full_version()"
</pre>

=== Обновление с PostGIS 2.5 на PostGIS 3.x ===
Если предыдущий запрос <code>SELECT PostGIS_full_version()</code> отображает информацию подобно такой:
<pre>
POSTGIS="3.3.4 3.3.4" [EXTENSION] . . .
. . .
[UNPACKAGED!] (raster procs from "2.5.5 r0" need upgrade)
</pre>
То следующая информация для вас.

Между версиям PosGIS 2 и 3 существует некоторая разница, которая требует дополнительных действий при обновлении. Если вы после выполнения предыдущего запроса не увидели такой проблем, то следующие действия выполнять не нужно — переходите к следующему разделу.
<pre>
# дважды один и тот же запрос
sudo -u postgres psql -d postgres -A -t -c "SELECT postgis_extensions_upgrade()"
sudo -u postgres psql -d postgres -A -t -c "SELECT postgis_extensions_upgrade()"
sudo -u postgres psql -d postgres -A -t -c "DROP EXTENSION postgis_raster"
<pre>

=== Установить новые версии пакетов ===
А также удалить старый пакет postgis версии 2, если он был.
<pre>
sudo apt install -y postgresql-17 postgresql-17-postgis-3
sudo apt purge postgresql-11-postgis-2.5
</pre>

=== Сделать запасную резервную копию базы данных и настроек ===
Инструмент миграции кластеров между версиями делает это абсолютно безопасно, однако дополнительная осторожность лишней не будет. Сделайте запасные временные резервные копии, которые в конце обновления можно будет удалить.
<pre>
sudo -u postgres pg_dump --no-acl -Fp -Z 5 userside --file=/backup/userside_emergency.sql.gz
sudo -u postgres pg_dump --no-acl -Fc userside --file=/backup/userside_emergency.dump
sudo tar czf /backup/postgres_config_emergency.tgz -C /etc/postgresql/11/main .
</pre>
Каталог /backup должен существовать и должен быть доступен для записи всем пользователям.

=== Удалить кластер БД, созданный автоматически сценарием при установке новой версии ===
При помощи утилиты <code>pg_lsclusters</code> из postgresql-common посмотрите, как выглядят ваши кластеры БД:
<pre>
sudo pg_lsclusters
</pre>
Вывод команды будет примерно следующим:
<pre>
Ver Cluster Port Status Owner Data directory Log file
11 main 5432 online postgres /var/lib/postgresql/11/main /var/log/postgresql/postgresql-11.log
17 main 5433 online postgres /var/lib/postgresql/17/main /var/log/postgresql/postgresql-17.log
</pre>
Кластер 17/main был создан автоматически сценарием установки postgresql и использует новый порт 5433. Его нужно остановить и удалить — он не нужен, т.к. будет выполняться процедура миграции кластера, которая создаст новый кластер автоматически.
<pre>
sudo pg_dropcluster 17 main --stop
</pre>
Повторное выполнение команды <code>pg_lsclusters</code> должно показать, что у вас остался один кластер '''11/main'''.

=== Выполнить обновление кластера БД старой версии до кластера новой версии ===
Остановите службу postgresql
<pre>
sudo systemctl stop postgresql
</pre>
Запустите процесс обновления кластера БД '''11/main''' используя утилиту <code>pg_upgradecluster</code> из пакета postgresql-common. Это действие может занять много времени и дискового пространства.
<pre>
sudo pg_upgradecluster 11 main
</pre>
После завершения операции обновления вы увидите новое состояние кластеров (старая версия должна находиться в режиме '''down''' и порт 5432 теперь используется новым кластером):
<pre>
Ver Cluster Port Status Owner Data directory Log file
11 main 5433 down postgres /var/lib/postgresql/11/main /var/log/postgresql/postgresql-11.log
17 main 5432 online postgres /var/lib/postgresql/17/main /var/log/postgresql/postgresql-17.log
</pre>
Запустите службу postgres
<pre>
sudo systemctl start postgresql
</pre>

=== Проверить работу USERSIDE ===
Сначала выполните команды, отображающие версии, чтобы убедиться что база данных теперь работает на кластере БД новой версии:
<pre>
sudo -u postgres psql -d userside -A -t -c "SELECT VERSION()"
sudo -u postgres psql -d userside -A -t -c "SELECT PostGIS_full_version()"
</pre>
Вы должны увидеть 17ю версию postgresql и 3.x.x версию postgis.

Теперь запустите службу FPM и зайдите в USERSIDE через браузер.
<pre>
sudo systemctl start php8.3-fpm
</pre>
Так как другие службы остановлены, вы, вероятно, увидите ошибки связанные с ними, но при этом интерфейс USERSIDE должен открыться без ошибок подключения к базе данных.
Если все успешно, то раскомментируйте закомментированные ранее строки в crontab и запустите внешние службы, находящиеся под управлением supervisor:
<pre>
sudo supervisorctl start all
sudo supervisorctl status
</pre>

=== Удалить кластер БД старой версии, устаревшие пакеты и запасные резервные копии ===
Если USERSIDE работает корректно, ошибок взаимодействия с БД нет, то можно удалить старый кластер и пакеты. Вы также, по желанию, можете удалить аварийные резервные копии или подождать несколько дней, чтобы точно убедиться, что они не пригодятся.
<pre>
sudo pg_dropcluster 11 main --stop
sudo apt purge -y postgresql-11 postgresql-11-postgis-3
sudo apt autoremove -y
sudo rm /backup/userside_emergency* /backup/postgres_config_emergency.tgz
sudo rm -rf /var/lib/postgresql/11/main
</pre>

HOWTO: Обновление версии PostgreSQL

2025-08-20T18:09:47Z

Uscld2:

[[HOWTO:_PostgreSQL_version_upgrade|en]] | [[HOWTO:_Обновление_версии_PostgreSQL|ru]]

В данном разделе описана процедура обновления PostgreSQL ''между основными версиями'' (например, с версии 11 на версию 17).

Обновление внутри версии (например, с версии 17.1 на версию 17.2) ''происходит автоматически и не требует дополнительных действий''.

'''Рекомендуем ознакомиться с официальными инструкциями по обновлению''' на сайте [https://www.postgresql.org/docs/current/upgrading.html postgresql.org].

В дистрибутиве Debian и основанных на нем существует пакет [https://packages.debian.org/sid/postgresql-common postgresql-common], устанавливаемый автоматически при установке пакета PostgreSQL. В состав postgresql-common входят инструменты, упрощающие работу с кластерами баз данных PostgreSQL. В том числе и обновление кластеров БД.

Кластером баз данных ([https://www.postgresql.org/docs/current/glossary.html Database cluster]) в PostgreSQL называется экземпляр сервера вместе со всеми обслуживаемыми БД, а не распределенную систему, как может показаться.

В следующем примере будет показано обновление кластера БД с версии 11 на версию 17 используя инструменты из пакета '''postgresql-common'''.

== Порядок обновления ==
# Остановить USERSIDE.
# Обновить текущую версии postgresql в пределах основной версии (например, с 11.5 до 11.22).
# Обновить расширение postgis до самой последней версии (например, с 2.5 до 3.3.4). Также обязательно обновить расширение и в самой базе данных.
# Установить новую версию postgresql не удаляя старой (например 17.1)
# Сделать запасную резервную копию базы данных и настроек
# Удалить кластер БД, созданный автоматически сценарием при установке новой версии
# Выполнить обновление кластера БД старой версии до кластера новой версии
# Проверить работу USERSIDE
# Удалить кластер БД старой версии, устаревшие пакеты и запасные резервные копии

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

[https://asciinema.org/a/do2AE0z30mg5JLIuI9zhGTPoR Посмотреть видеоинструкцию на asciinema].

== Пошаговая инструкция ==
SQL-запросы с оператором <code>SELECT</code>, приведенные далее, необходимы для определения текущих установленных версий в качестве справочной информации.

=== Остановить USERSIDE ===
<pre>
sudo supervisorctl stop all
sudo systemctl stop php8.3-fpm
</pre>
Версия php указана для примера. Используйте ту, что испльзуется у вас.

Закомментируйте запуск всех модулей и userside в crontab.

=== Обновить текущую версии postgresql в пределах основной версии ===
Проверить текущие версии системных пакетов PostgreSQL и PostGIS. Обновить текущие установленные версии PostgreSQL и PostGIS до посладних версий, а также, если текущая версия PostGIS ниже 3, установить дополнительно пакет PostGIS 3 для вашей версии PostgreSQL. Если у вас уже сейчас установлен PostGIS 3, то вам нужно только лишь его обновить до последней версии.
<pre>
sudo -u postgres psql -d userside -A -t -c "SELECT VERSION()"
sudo -u postgres psql -d userside -A -t -c "SELECT PostGIS_full_version()"

sudo apt update
sudo apt install --only-upgrade -y postgresql-11 postgresql-11-postgis-2.5
# только если текущая версия postgis ниже 3
sudo apt install -y postgresql-11-postgis-3
</pre>
Вместо 11 и 2.5 укажите те версии, которе фактически установлены у вас.

=== Обновить расширение postgis до самой последней версии ===
Обязательно также обновить расширение postgis в самих базах данных! У вас может быть несколько баз данных, в которые установлено это расширение. Например, у вас на сервре есть еще тестовая база данных (копия основной для тестов). Проверьте все существующие базы данных сервера на наличие расширения PostGIS и обновите его в каждой базе данных. Вы можете просто попытаться обновить расширение во всех базах данных, там где его нет — будет просто ошибка обновления. Далее показано как обновить в базе данных userisde. Проделайте это для всех баз данных, в которые оно установлено.
<pre>
sudo -u postgres psql -d userside -A -t -c "ALTER EXTENSION postgis UPDATE"
sudo -u postgres psql -d userside -A -t -c "SELECT PostGIS_full_version()"
</pre>

=== Обновление с PostGIS 2.5 на PostGIS 3.x
Если предыдущий запрос <code>SELECT PostGIS_full_version()</code> отображает информацию подобно такой:
<pre>
POSTGIS="3.3.4 3.3.4" [EXTENSION] . . .
. . .
[UNPACKAGED!] (raster procs from "2.5.5 r0" need upgrade)
</pre>
То следующая информация для вас.

Между версиям PosGIS 2 и 3 существует некоторая разница, которая требует дополнительных действий при обновлении. Если вы после выполнения предыдущего запроса не увидели такой проблем, то следующие действия выполнять не нужно — переходите к следующему разделу.
<pre>
# дважды один и тот же запрос
sudo -u postgres psql -d postgres -A -t -c "SELECT postgis_extensions_upgrade()"
sudo -u postgres psql -d postgres -A -t -c "SELECT postgis_extensions_upgrade()"
sudo -u postgres psql -d postgres -A -t -c "DROP EXTENSION postgis_raster"
<pre>

=== Установить новые версии пакетов ===
А также удалить старый пакет postgis версии 2, если он был.
<pre>
sudo apt install -y postgresql-17 postgresql-17-postgis-3
sudo apt purge postgresql-11-postgis-2.5
</pre>

=== Сделать запасную резервную копию базы данных и настроек ===
Инструмент миграции кластеров между версиями делает это абсолютно безопасно, однако дополнительная осторожность лишней не будет. Сделайте запасные временные резервные копии, которые в конце обновления можно будет удалить.
<pre>
sudo -u postgres pg_dump --no-acl -Fp -Z 5 userside --file=/backup/userside_emergency.sql.gz
sudo -u postgres pg_dump --no-acl -Fc userside --file=/backup/userside_emergency.dump
sudo tar czf /backup/postgres_config_emergency.tgz -C /etc/postgresql/11/main .
</pre>
Каталог /backup должен существовать и должен быть доступен для записи всем пользователям.

=== Удалить кластер БД, созданный автоматически сценарием при установке новой версии ===
При помощи утилиты <code>pg_lsclusters</code> из postgresql-common посмотрите, как выглядят ваши кластеры БД:
<pre>
sudo pg_lsclusters
</pre>
Вывод команды будет примерно следующим:
<pre>
Ver Cluster Port Status Owner Data directory Log file
11 main 5432 online postgres /var/lib/postgresql/11/main /var/log/postgresql/postgresql-11.log
17 main 5433 online postgres /var/lib/postgresql/17/main /var/log/postgresql/postgresql-17.log
</pre>
Кластер 17/main был создан автоматически сценарием установки postgresql и использует новый порт 5433. Его нужно остановить и удалить — он не нужен, т.к. будет выполняться процедура миграции кластера, которая создаст новый кластер автоматически.
<pre>
sudo pg_dropcluster 17 main --stop
</pre>
Повторное выполнение команды <code>pg_lsclusters</code> должно показать, что у вас остался один кластер '''11/main'''.

=== Выполнить обновление кластера БД старой версии до кластера новой версии ===
Остановите службу postgresql
<pre>
sudo systemctl stop postgresql
</pre>
Запустите процесс обновления кластера БД '''11/main''' используя утилиту <code>pg_upgradecluster</code> из пакета postgresql-common. Это действие может занять много времени и дискового пространства.
<pre>
sudo pg_upgradecluster 11 main
</pre>
После завершения операции обновления вы увидите новое состояние кластеров (старая версия должна находиться в режиме '''down''' и порт 5432 теперь используется новым кластером):
<pre>
Ver Cluster Port Status Owner Data directory Log file
11 main 5433 down postgres /var/lib/postgresql/11/main /var/log/postgresql/postgresql-11.log
17 main 5432 online postgres /var/lib/postgresql/17/main /var/log/postgresql/postgresql-17.log
</pre>
Запустите службу postgres
<pre>
sudo systemctl start postgresql
</pre>

=== Проверить работу USERSIDE ===
Сначала выполните команды, отображающие версии, чтобы убедиться что база данных теперь работает на кластере БД новой версии:
<pre>
sudo -u postgres psql -d userside -A -t -c "SELECT VERSION()"
sudo -u postgres psql -d userside -A -t -c "SELECT PostGIS_full_version()"
</pre>
Вы должны увидеть 17ю версию postgresql и 3.x.x версию postgis.

Теперь запустите службу FPM и зайдите в USERSIDE через браузер.
<pre>
sudo systemctl start php8.3-fpm
</pre>
Так как другие службы остановлены, вы, вероятно, увидите ошибки связанные с ними, но при этом интерфейс USERSIDE должен открыться без ошибок подключения к базе данных.
Если все успешно, то раскомментируйте закомментированные ранее строки в crontab и запустите внешние службы, находящиеся под управлением supervisor:
<pre>
sudo supervisorctl start all
sudo supervisorctl status
</pre>

=== Удалить кластер БД старой версии, устаревшие пакеты и запасные резервные копии ===
Если USERSIDE работает корректно, ошибок взаимодействия с БД нет, то можно удалить старый кластер и пакеты. Вы также, по желанию, можете удалить аварийные резервные копии или подождать несколько дней, чтобы точно убедиться, что они не пригодятся.
<pre>
sudo pg_dropcluster 11 main --stop
sudo apt purge -y postgresql-11 postgresql-11-postgis-3
sudo apt autoremove -y
sudo rm /backup/userside_emergency* /backup/postgres_config_emergency.tgz
sudo rm -rf /var/lib/postgresql/11/main
</pre>

HOWTO: PostgreSQL version upgrade

2025-08-20T12:13:47Z

Uscld2:

[[HOWTO:_PostgreSQL_version_upgrade|en]] | [[HOWTO:_Обновление_версии_PostgreSQL|ru]]

This section describes how to upgrade PostgreSQL ''between major versions'' (e.g., from version 11 to version 17).

Upgrading within a version (e.g., from version 17.1 to version 17.2) ''is automatic and requires no additional steps.''

'''We recommend reading the official upgrade instructions''' at [https://www.postgresql.org/docs/current/upgrading.html postgresql.org].

In the Debian distribution and those based on it, there is a package [https://packages.debian.org/sid/postgresql-common postgresql-common] that is installed automatically when the PostgreSQL package is installed. Postgresql-common includes tools to simplify working with PostgreSQL database clusters. This includes updating database clusters.

A [https://www.postgresql.org/docs/current/glossary.html database cluster] in PostgreSQL is a server instance together with all the maintained databases, not a distributed system as it may seem.

The following example will show how to upgrade a database cluster from version 11 to version 17 using the tools in the '''postgresql-common''' package.

== Upgrade order ==
# Stop USERSIDE.
# Upgrade the current version of postgresql within the major version (e.g., from 11.5 to 11.22).
# Upgrade the postgis extension to the latest version (e.g. from 2.5 to 3.3.4). Also be sure to update the extension in the database itself.
# Install a new version of postgresql without uninstalling the old one (e.g. 17.1).
# Make a backup copy of the database and settings
# Delete the database cluster created automatically by the script when installing the new version
# Upgrade the database cluster of the old version to the cluster of the new version
# Check USERSIDE operation
# Remove the old version database cluster, obsolete packages and spare backups

Allocate time for this operation. It can take quite a long time depending on the size of the database and the performance of the server. Also, make sure you have the free space you will need to upgrade the cluster (at least as much as the current cluster, but more is better).

[https://asciinema.org/a/do2AE0z30mg5JLIuI9zhGTPoR View video tutorial on asciinema].

== Step-by-step instructions ==

=== Stop USERSIDE ===
<pre>
sudo supervisorctl stop all
sudo systemctl stop php8.1-fpm
</pre>
The php version is for example. Use the one you are using.

Comment out the startup of all modules and userside in crontab.

=== Upgrade the current version of postgresql within the major version ===
Check the current versions. Upgrade the current PostgreSQL and PostGIS packages:
<pre>
sudo -u postgres psql -d userside -A -t -c "SELECT VERSION()"
sudo -u postgres psql -d userside -A -t -c "SELECT PostGIS_full_version()"
sudo -u postgres psql -d postgres -A -t -c "SELECT PostGIS_full_version()"

sudo apt update
sudo apt install --only-upgrade -y postgresql-11 postgresql-11-postgis-2.5
</pre>
Instead of 11 and 2.5, specify the versions you actually have installed.

=== Upgrade the postgis extension to the latest version ===
Be sure to upgrade the extension in the database as well! If the previous commands also showed the presence of an extension in the postgres database, then postgis needs to be updated for it as well.
<pre>
sudo apt install -y postgresql-11-postgis-3

sudo -u postgres psql -d userside -A -t -c "ALTER EXTENSION postgis UPDATE"
sudo -u postgres psql -d userside -A -t -c "SELECT PostGIS_full_version()"

sudo -u postgres psql -d postgres -A -t -c "ALTER EXTENSION postgis UPDATE"
sudo -u postgres psql -d postgres -A -t -c "SELECT PostGIS_full_version()"
</pre>

=== Install a new version of postgresql without uninstalling the old one ===
<pre>
sudo apt install -y postgresql-17 postgresql-17-postgis-3
</pre>

=== Make a backup of the database and settings ===
The number 11 in the filename is the PostgreSQL version number to which this backup belongs.
<pre>
sudo -u postgres pg_dump --no-acl -Fp -Z 5 userside --file=/backup/userside_emergency_11.sql.gz
sudo -u postgres pg_dump --no-acl -Fc userside --file=/backup/userside_emergency_11.dump
sudo tar czf /backup/postgres_config_emergency_11.tgz -C /etc/postgresql/11/main .
</pre>
The /backup directory must exist and must be writable by all users.

=== Remove the database cluster created automatically by the script when installing a new version ===
Using the <code>pg_lsclusters</code> utility from postgresql-common, see what your database clusters look like:
<pre>
sudo pg_lsclusters
</pre>
The output of the command will be approximately as follows:
<pre>
Ver Cluster Port Status Owner Data directory Log file
11 main 5432 online postgres /var/lib/postgresql/11/main /var/log/postgresql/postgresql-11.log
17 main 5433 online postgres /var/lib/postgresql/17/main /var/log/postgresql/postgresql-17.log
</pre>
The 17/main cluster was created automatically by the postgresql installation script. It needs to be stopped and deleted.
<pre>
sudo pg_dropcluster 17 main --stop
</pre>
Running the <code>pg_lsclusters</code> command again should show that you have one '''11/main''' cluster left.

=== Perform an upgrade of the old version database cluster to the new version database cluster ===
Stop the postgresql service
<pre>
sudo systemctl stop postgresql
</pre>
Start the '''11/main''' database cluster upgrade process using the <code>pg_upgradecluster</code> utility from the postgresql-common package. This may take a lot of time and disc space.
<pre>
sudo pg_upgradecluster 11 main
</pre>
After the upgrade operation is complete, you will see the new state of the clusters (the old version should be in '''down''' mode):
<pre>
Ver Cluster Port Status Owner Data directory Log file
11 main 5433 down postgres /var/lib/postgresql/11/main /var/log/postgresql/postgresql-11.log
17 main 5432 online postgres /var/lib/postgresql/17/main /var/log/postgresql/postgresql-17.log
</pre>
Start the postgres service
<pre>
sudo systemctl start postgresql
</pre>

=== Verify the operation of USERSIDE ===
First run the commands displaying the versions to verify that the database is now running on the new version database cluster:
<pre>
sudo -u postgres psql -d userside -A -t -c "SELECT VERSION()"
sudo -u postgres psql -d userside -A -t -c "SELECT PostGIS_full_version()"
</pre>
You should see version 17 of postgresql and version 3.3.4 of postgis. Maybe by the time you read these lines, the postgis version will be newer.

Now start the FPM service and go to USERSIDE through your browser.
<pre>
sudo systemctl start php8.1-fpm
</pre>
Since the other services are stopped, you will probably see errors related to them, but the USERSIDE interface should open without database connection errors.
If everything is successful, then uncomment the previously commented lines in crontab and start the external services under supervisor control:
<pre>
sudo supervisorctl start all
sudo supervisorctl status
</pre>

=== Remove the old version database cluster, obsolete packages, and spare backups ===
If USERSIDE is running correctly, and there are no database communication errors, you can remove the old cluster and packages. You can also optionally delete the emergency backups or wait a few days to make sure they are not needed.
<pre>
sudo pg_dropcluster 11 main --stop
sudo apt purge -y postgresql-11 postgresql-11-postgis-2.5 postgresql-11-postgis-3
sudo apt autoremove -y
sudo rm /backup/userside_emergency_11* /backup/postgres_config_emergency_11.tgz
sudo rm -rf /var/lib/postgresql/11/main
</pre>

HOWTO: Обновление версии PostgreSQL

2025-08-20T12:11:56Z

Uscld2:

[[HOWTO:_PostgreSQL_version_upgrade|en]] | [[HOWTO:_Обновление_версии_PostgreSQL|ru]]

В данном разделе описана процедура обновления PostgreSQL ''между основными версиями'' (например, с версии 11 на версию 17).

Обновление внутри версии (например, с версии 17.1 на версию 17.2) ''происходит автоматически и не требует дополнительных действий''.

'''Рекомендуем ознакомиться с официальными инструкциями по обновлению''' на сайте [https://www.postgresql.org/docs/current/upgrading.html postgresql.org].

В дистрибутиве Debian и основанных на нем существует пакет [https://packages.debian.org/sid/postgresql-common postgresql-common], устанавливаемый автоматически при установке пакета PostgreSQL. В состав postgresql-common входят инструменты, упрощающие работу с кластерами баз данных PostgreSQL. В том числе и обновление кластеров БД.

Кластером баз данных ([https://www.postgresql.org/docs/current/glossary.html Database cluster]) в PostgreSQL называется экземпляр сервера вместе со всеми обслуживаемыми БД, а не распределенную систему, как может показаться.

В следующем примере будет показано обновление кластера БД с версии 11 на версию 17 используя инструменты из пакета '''postgresql-common'''.

== Порядок обновления ==
# Остановить USERSIDE.
# Обновить текущую версии postgresql в пределах основной версии (например, с 11.5 до 11.22).
# Обновить расширение postgis до самой последней версии (например, с 2.5 до 3.3.4). Также обязательно обновить расширение и в самой базе данных.
# Установить новую версию postgresql не удаляя старой (например 17.1)
# Сделать запасную резервную копию базы данных и настроек
# Удалить кластер БД, созданный автоматически сценарием при установке новой версии
# Выполнить обновление кластера БД старой версии до кластера новой версии
# Проверить работу USERSIDE
# Удалить кластер БД старой версии, устаревшие пакеты и запасные резервные копии

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

[https://asciinema.org/a/do2AE0z30mg5JLIuI9zhGTPoR Посмотреть видеоинструкцию на asciinema].

== Пошаговая инструкция ==
SQL-запросы с оператором <code>SELECT</code>, приведенные далее, необходимы для определения текущих установленных версий в качестве справочной информации.

=== Остановить USERSIDE ===
<pre>
sudo supervisorctl stop all
sudo systemctl stop php8.3-fpm
</pre>
Версия php указана для примера. Используйте ту, что испльзуется у вас.

Закомментируйте запуск всех модулей и userside в crontab.

=== Обновить текущую версии postgresql в пределах основной версии ===
Проверить текущие версии. Обновить текущие пакеты PostgreSQL и PostGIS:
<pre>
sudo -u postgres psql -d userside -A -t -c "SELECT VERSION()"
sudo -u postgres psql -d userside -A -t -c "SELECT PostGIS_full_version()"
sudo -u postgres psql -d postgres -A -t -c "SELECT PostGIS_full_version()"

sudo apt update
sudo apt install --only-upgrade -y postgresql-11 postgresql-11-postgis-2.5
</pre>
Вместо 11 и 2.5 укажите те версии, которе фактически установлены у вас.

=== Обновить расширение postgis до самой последней версии ===
Обязательно также обновить расширение в базе данных! Если предыдущие команды также показали наличие расширения в базе данных postgres, то postgis нужно обновить и для нее.
<pre>
sudo apt install -y postgresql-11-postgis-3

sudo -u postgres psql -d postgres -A -t -c "ALTER EXTENSION postgis UPDATE"
sudo -u postgres psql -d postgres -A -t -c "SELECT PostGIS_full_version()"

sudo -u postgres psql -d userside -A -t -c "ALTER EXTENSION postgis UPDATE"
sudo -u postgres psql -d userside -A -t -c "SELECT PostGIS_full_version()"
</pre>

=== Установить новую версию postgresql не удаляя старой ===
<pre>
sudo apt install -y postgresql-17 postgresql-17-postgis-3
</pre>

=== Сделать запасную резервную копию базы данных и настроек ===
Число 11 в имени файлов — это номер версии PostgreSQL, к которой относится эта резервная копия.
<pre>
sudo -u postgres pg_dump --no-acl -Fp -Z 5 userside --file=/backup/userside_emergency_11.sql.gz
sudo -u postgres pg_dump --no-acl -Fc userside --file=/backup/userside_emergency_11.dump
sudo tar czf /backup/postgres_config_emergency_11.tgz -C /etc/postgresql/11/main .
</pre>
Каталог /backup должен существовать и должен быть доступен для записи всем пользователям.

=== Удалить кластер БД, созданный автоматически сценарием при установке новой версии ===
При помощи утилиты <code>pg_lsclusters</code> из postgresql-common посмотрите, как выглядят ваши кластеры БД:
<pre>
sudo pg_lsclusters
</pre>
Вывод команды будет примерно следующим:
<pre>
Ver Cluster Port Status Owner Data directory Log file
11 main 5432 online postgres /var/lib/postgresql/11/main /var/log/postgresql/postgresql-11.log
17 main 5433 online postgres /var/lib/postgresql/17/main /var/log/postgresql/postgresql-17.log
</pre>
Кластер 17/main был создан автоматически сценарием установки postgresql. Его нужно остановить и удалить.
<pre>
sudo pg_dropcluster 17 main --stop
</pre>
Повторное выполнение команды <code>pg_lsclusters</code> должно показать, что у вас остался один кластер '''11/main'''.

=== Выполнить обновление кластера БД старой версии до кластера новой версии ===
Остановите службу postgresql
<pre>
sudo systemctl stop postgresql
</pre>
Запустите процесс обновления кластера БД '''11/main''' используя утилиту <code>pg_upgradecluster</code> из пакета postgresql-common. Это действие может занять много времени и дискового пространства.
<pre>
sudo pg_upgradecluster 11 main
</pre>
После завершения операции обновления вы увидите новое состояние кластеров (старая версия должна находиться в режиме '''down'''):
<pre>
Ver Cluster Port Status Owner Data directory Log file
11 main 5433 down postgres /var/lib/postgresql/11/main /var/log/postgresql/postgresql-11.log
17 main 5432 online postgres /var/lib/postgresql/17/main /var/log/postgresql/postgresql-17.log
</pre>
Запустите службу postgres
<pre>
sudo systemctl start postgresql
</pre>

=== Проверить работу USERSIDE ===
Сначала выполните команды, отображающие версии, чтобы убедиться что база данных теперь работает на кластере БД новой версии:
<pre>
sudo -u postgres psql -d userside -A -t -c "SELECT VERSION()"
sudo -u postgres psql -d userside -A -t -c "SELECT PostGIS_full_version()"
</pre>
Вы должны увидеть 17ю версию postgresql и 3.3.4 версию postgis. Может быть к тому времени, как вы будете читать эти строки, версия postgis будет более новой.

Теперь запустите службу FPM и зайдите в USERSIDE через браузер.
<pre>
sudo systemctl start php8.3-fpm
</pre>
Так как другие службы остановлены, вы, вероятно, увидите ошибки связанные с ними, но при этом интерфейс USERSIDE должен открыться без ошибок подключения к базе данных.
Если все успешно, то раскомментируйте закомментированные ранее строки в crontab и запустите внешние службы, находящиеся под управлением supervisor:
<pre>
sudo supervisorctl start all
sudo supervisorctl status
</pre>

=== Удалить кластер БД старой версии, устаревшие пакеты и запасные резервные копии ===
Если USERSIDE работает корректно, ошибок взаимодействия с БД нет, то можно удалить старый кластер и пакеты. Вы также, по желанию, можете удалить аварийные резервные копии или подождать несколько дней, чтобы точно убедиться, что они не пригодятся.
<pre>
sudo pg_dropcluster 11 main --stop
sudo apt purge -y postgresql-11 postgresql-11-postgis-2.5 postgresql-11-postgis-3
sudo apt autoremove -y
sudo rm /backup/userside_emergency_11* /backup/postgres_config_emergency_11.tgz
sudo rm -rf /var/lib/postgresql/11/main
</pre>

Обновление 3.18

2025-07-08T11:34:18Z

Uscld2:

[[Upgrade_3.18|en]] | [[Обновление_3.18|ru]]

Версия: '''[[3.18]]'''

Требуется версия: '''[[3.12]] и выше'''

== Несколько слов от автора ==
* Мы двигаемся дальше. Это "военная версия" 3.18. Её разработка была долгая и осложнённая военными действиями, перебоями с энергоснабжением и многим другим.

* Сделано немало и опять же особенно мы старались сделать упор на доработку всяческих мелочей. Прошу вдумчиво ознакомиться со [[3.18|списком изменений]]

* Обратите внимание на страницу [["Горячие клавиши"]]

* В версии 3.18 объявляются устаревшими разделы:
** "[[Заявка на подключение]]". В версии 3.19 раздел будет удалён. Используйте раздел "[[API]]" для организации приема заявок и создания задач
** "[[Общая схема коммутации]]". В версии 3.19 раздел будет удалён. Используйте в работе раздел "[[Схемы коммутации]]"

* [[Обновление]]. '''Рекомендую иметь два инстанса системы'''. Отдельно действующую и отдельно тестовую. На тестовой вы можете периодически обновлять базу данных с действующей системы и проводить обновление, убеждаясь, что всё работает, ознакомиться с нововведениями или выявлять моменты, которые у вас перестали работать.

* Наша группа в Telegram для взаимного общения клиентов между собой: https://t.me/usersideeu и канал для новостей: https://t.me/userside

== Особенности в проведении обновления ==

При обновлении в Docker-окружении, обратитесь к [https://github.com/userside/userside-docker/tree/v3.18 инструкциям] в репозитории Docker-бандла.

* Если вы обновляетесь с версии 3.10 - ознакомьтесь со страницей: [[Обновление 3.11]]

* Если вы обновляетесь с версии 3.11 и ранее - ознакомьтесь со страницей: [[Обновление 3.12]]

* Если вы обновляетесь с версии 3.12 и ранее - ознакомьтесь со страницей: [[Обновление 3.13]]

* Если вы обновляетесь с версии 3.13 и ранее - ознакомьтесь со страницей: [[Обновление 3.14]]

* Если вы обновляетесь с версии 3.14 и ранее - ознакомьтесь со страницей: [[Обновление 3.15]]

* Если вы обновляетесь с версии 3.15 и ранее - ознакомьтесь со страницей: [[Обновление 3.16]]

* Если вы обновляетесь с версии 3.16 и ранее - ознакомьтесь со страницей: [[Обновление 3.17]]

* Версия 3.18 требует PHP версии 8.1. Вы можете установить все необходимые пакеты дополнительно к уже существующей иной версии PHP. Если используете LDAP, то установите также php8.1-ldap. Если используете TurboSMS, то установите php8.1-soap.
sudo apt install -y php8.1-{fpm,cli,common,curl,intl,mbstring,opcache,pgsql,readline,xml,zip,snmp,gd}

* Если версия php8.1 отсутствует в вашем репозитории, то воспользуйтесь альтернативным репозиторием, например, deb.sury.org, добавив его в систему следующим образом и затем повторив команду установки PHP8.1 приведенную пунктом выше:
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

* Измените конфигурацию PHP следующим образом и перезапустите службу php-fpm.
Обратите внимание, что если ваш часовой пояс <code>Europe/Kiev</code>, то вместо <code>$(cat /etc/timezone)</code> Вы должны написать <code>Europe/Kyiv</code>. В Debian 11 еще не внесены изменения по переименованию часового пояса, в то время как в PHP 8.1 изменения уже внесены.
<pre>
sudo sed -i "s@^;date.timezone.*@date.timezone = $(cat /etc/timezone)@" /etc/php/8.1/fpm/php.ini
sudo sed -i "s@^;date.timezone.*@date.timezone = $(cat /etc/timezone)@" /etc/php/8.1/cli/php.ini
sudo sed -i "s@;cgi.fix_pathinfo=1@cgi.fix_pathinfo=0@" /etc/php/8.1/fpm/php.ini
sudo sed -i "s@post_max_size = 8M@post_max_size = 100M@" /etc/php/8.1/fpm/php.ini
sudo sed -i "s@upload_max_filesize = 2M@upload_max_filesize = 100M@" /etc/php/8.1/fpm/php.ini
sudo sed -i "s@max_execution_time.*@max_execution_time = 300@" /etc/php/8.1/fpm/php.ini
sudo sed -i "s@max_input_time.*@max_input_time = 300@" /etc/php/8.1/fpm/php.ini

sudo systemctl restart php8.1-fpm
</pre>

* В NGINX измените используемую версию PHP для обновляемой копии USERSIDE. Если вы следовали инструкциям по установке системы, то в файле /etc/nginx/conf.d/default.conf или userside.conf или в другом, который вы использовали для настройки userside, измените строку:
fastcgi_pass unix:/run/php/php7.4-fpm.sock;
на строку
fastcgi_pass unix:/run/php/php8.1-fpm.sock;
и перечитайте конфигурацию nginx:
sudo nginx -s reload

* Обратите внимание, что при вызове команды <code>php</code> из командной строки, теперь будет вызываться php8.1, так как это последняя установленная версия. Если вы где-либо до сих пор используете php7.4, то вам нужно изменить вызов php в этих местах либо изменить альтернативную команду php, чтобы она запускала нужную вам версию.

* USERSIDE 3.18 ''требует Python3 любой поддерживаемой на данный момент версии. Статус версий можно посмотреть здесь: "[https://devguide.python.org/versions/ Status of Python versions]". Рекомендуется использовать версию с состоянием "security" или "bugfix". Версии отмеченные как "end-of-life" не поддерживаются. Отмеченные как "feature" не рекомендуется использовать. Если у вас на хосте неподдерживаемая версия ("end-of-life"), то нужно обязательно [[Python-update|установить дополнительно]] более свежую версию Python.''

* Остановите супервизор и все контролируемые им службы:
sudo systemctl stop supervisor

* Теперь консольный скрипт, запускающий различные команды из командной строки, имеет имя <code>run</code> вместо <code>userside</code>. Вам нужно изменить везде команду запуска с <code>php /var/www/userside/userside</code> на <code>php /var/www/userside/run</code>.
** В файле /etc/cron.d/userside нужно заменить строку:
* * * * * www-data /usr/bin/php /var/www/userside/userside cron > /dev/null
на строку:
* * * * * www-data /usr/bin/php /var/www/userside/run cron > /dev/null
** В файле /etc/supervisor/conf.d/us-core-worker.conf нужно заменить строку:
command=/usr/bin/php /var/www/userside/userside queue/listen
на строку:
command=/usr/bin/php /var/www/userside/run queue/listen

* Пользователю RabbitMQ, который используется в USERSIDE, необходимо дать права на мониторинг, чтобы USERSIDE мог осуществлять мониторинг работы сервера. Для этого выполните (при условии, что имя вашего пользователя <code>userside</code>):
sudo rabbitmqctl set_user_tags "userside" "monitoring"
Если вы используете vhost оличный от корневого (по умолчанию), то также нужно добавить соответствующую опцию, например для vhost <code>copy</code>:
sudo rabbitmqctl --vhost copy set_user_tags "userside" "monitoring"

* Удалите рудиментарные очереди:
<pre>
sudo rabbitmqctl delete_queue userside.core
sudo rabbitmqctl delete_queue userside.microservice.poller
</pre>

* С помощью автоматического [[Инсталлятор|инсталлятора]] выполните [[Обновление|обновление]]:
sudo -u www-data php userside_install.phar install

* Следующее действие нужно выполнять только если вы [[Python-update|обновили Python]]. Если не обновляли, можно не выполнять:
sudo rm -rf /var/www/userside/microservice/poller/venv
sudo python3.11 -m venv /var/www/userside/microservice/poller/venv

* Необходимо обновить (установить) зависимости для поллера:
cd /var/www/userside/microservice/poller
sudo venv/bin/pip3 install --upgrade pip
sudo venv/bin/pip3 install -U -r requirements.txt

* Обратите внимание, что начиная с версии 3.18, фоновыми службами выполняется значительная часть работы по взаимодействию с сетевым оборудованием. Запустите супервизор:
sudo systemctl start supervisor
И проследите, чтобы все службы запустились и работали корректно (RUNNING):
sudo supervisorctl status
Вы должны увидеть 5 экземпляров службы us-poller и 10 экземпляров службы us-core-worker, либо то количество, которое вы самостоятельно указали в конфигурационных файлах супервизора.

* Начиная с версии 3.18 вместо модулей сателлитов (usm_satellite), устанавливаемых на удаленных узлах для проксирования команд взаимодействия с оборудованием, теперь используются точно такие же поллеры, как и в ядре системы, но с обязательным указанием идентификатора "сетеллита" в настройках. Обязательно ознакомьтесь с действиями, необходимыми для перехода с usm_satellite на usm_poller [[Сателлиты|в соответствующем разделе]].

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

* Переработан низкоуровневый опрос оборудования ''(FDB, ARP, опрос интерфейсов и т.п.)''. Всё это теперь выполняется поллерами ядра. После обновления проверьте работоспособность опроса FDB-таблиц и прочего.

* Метки абонентов объединены с общими метками по системе. Соответственно в файлах конфигурации модулей взаимодействия с биллингами (либо в API) требуется изменить ID меток на новые (если вы это используете). Например для модуля usm_utm5 это переменная $markMerge

* Удалена работа с JABBER. Используйте службу уведомлений "Custom HTTP request" либо Messenger ''(Telegram)''

* Если вы до сих пор не перенастроили API-ключ [[UserSide API Key|на новую систему]] - сделайте это. В версии 3.18 $zapikey удален и API-перестанет работать для тех, кто не провёл перенастройку.

* Если в версии 3.17 вы до сих пор не [[Обновление 3.17|настроили работу с WebSTOMP]] - нужно это сделать иначе перестанет работать часть системы

* Не забудьте обновить все модули на их свежие версии

* В полере (usm_poller) который теперь используется для взаимодействия с оборудованием, для аутентификации в SNMP v1 и v2 используется одно комьюнити. Но в пользовательском интерфейсе USERSIDE для обратной совместимости пока что оставлены два поля (ro и rw). Какое из значений будет использовано описано ниже в алгоритме выбора единственного SNMP-community. Чтобы упростить для себя эту задачу, вы можете использовать одно и то же комьюнити для двух полей. Например, если вы хотите предоставить для Userside доступ только на чтение, то в оба поля (ro и rw) впишите комьюнити с правами на чтение. Если хотите предоставить полный доступ, то также в оба поля впишите один и тот же комьюнити с полными правами. Также стоит учитывать, что незаполненное поле будет заполнено из глобальных настроек Userside.

[[Файл:Селектор SNMP-community.png|обрамить|центр]]

'''Список изменений:''' [[3.18|просмотреть]]

'''Проведение обновления:''' [[Обновление|инструкция]]

Upgrade 3.18

2025-07-08T11:34:09Z

Uscld2:

[[Upgrade_3.18|en]] | [[Обновление_3.18|ru]]

Version: '''[[3.18_EN|3.18]]'''

Version required: '''[[3.12_EN|3.12]]''' and above

== A few words from the author - version features ==

* A lot of work has been done and especially we have tried to emphasise on fine-tuning all sorts of little things. Please read the [[3.18_EN| list of changes]] thoughtfully.

* Please take a look at the [["Hot keys"]] page.

* Version 3.18 declares obsolete sections:
** "[[Application for connection]]". In version 3.19, the section will be removed. Use the "[[API_EN|API]]" section to organise receiving applications and creating tasks
** "[[General commutation scheme]]". In version 3.19, the section will be removed. Use the "[[Commutation schemes]]" section in your work

* [[Upgrade]]. '''Recommended to have two instances of the system'''. A separate running one and a separate test one. On the test one you can periodically update the database from the live system and perform updates to make sure everything is working, familiarise yourself with innovations or identify things that have stopped working for you.

* Our group in Telegram for mutual communication between clients: https://t.me/usersideeu and a channel for news: https://t.me/userside

== Features of the upgrade ==

When upgrading in a Docker environment, refer to [https://github.com/userside/userside-docker/tree/v3.18 instructions] in the Docker bundle repository.

* If you are upgrading from version 3.10 - check out the page: [[Upgrade 3.11]]

* If you are upgrading from version 3.11 and earlier - check out the page: [[Upgrade 3.12]]

* If you are upgrading from version 3.12 and earlier - check out the page: [[Upgrade 3.13]]

* If you are upgrading from version 3.13 and earlier - check out the page: [[Upgrade 3.14]]

* If you are upgrading from version 3.14 and earlier - check out the page: [[Upgrade 3.15]]

* If you are upgrading from version 3.15 and earlier - check out the page: [[Upgrade 3.16]]

* If you are upgrading from version 3.16 and earlier - check out the page: [[Upgrade 3.17]]

* Version 3.18 requires PHP version 8.1. You can install all the necessary packages in addition to your existing different PHP version. If you are using LDAP, also install php8.1-ldap. If you are using TurboSMS, install php8.1-soap.
sudo apt install -y php8.1-{fpm,cli,common,curl,intl,mbstring,opcache,pgsql,readline,xml,zip,snmp,gd}

* If php8.1 is not in your repository, use an alternative repository such as deb.sury.org by adding it to your system as follows and then repeating the PHP8.1 installation command above:
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

* Change the PHP configuration as follows and restart the php-fpm service.
Note that if your time zone is <code>Europe/Kiev</code>, then instead of <code>$(cat /etc/timezone)</code> You must write <code>Europe/Kyiv</code>. Debian 11 has not yet made the time zone renaming changes, while PHP 8.1 has already made the changes.
<pre>
sudo sed -i "s@^;date.timezone.*@date.timezone = $(cat /etc/timezone)@" /etc/php/8.1/fpm/php.ini
sudo sed -i "s@^;date.timezone.*@date.timezone = $(cat /etc/timezone)@" /etc/php/8.1/cli/php.ini
sudo sed -i "s@;cgi.fix_pathinfo=1@cgi.fix_pathinfo=0@" /etc/php/8.1/fpm/php.ini
sudo sed -i "s@post_max_size = 8M@post_max_size = 100M@" /etc/php/8.1/fpm/php.ini
sudo sed -i "s@upload_max_filesize = 2M@upload_max_filesize = 100M@" /etc/php/8.1/fpm/php.ini
sudo sed -i "s@max_execution_time.*@max_execution_time = 300@" /etc/php/8.1/fpm/php.ini
sudo sed -i "s@max_input_time.*@max_input_time = 300@" /etc/php/8.1/fpm/php.ini

sudo systemctl restart php8.1-fpm
</pre>

* In NGINX, change the PHP version used for the updated copy of USERSIDE. If you followed the system installation instructions, in /etc/nginx/conf.d/default.conf or userside.conf or whatever you used to configure userside, change the line:
fastcgi_pass unix:/run/php/php7.4-fpm.sock;
per line
fastcgi_pass unix:/run/php/php8.1-fpm.sock;
and reread the nginx configuration:
sudo nginx -s reload

* Note that when the command is invoked <code>php</code> from the command line, php8.1 will now be called, since it is the latest version installed. If you're still using php7.4 anywhere, you'll need to change the php call in those places or change the alternate php command to run the version you need.

* USERSIDE 3.18 ''requires Python3 of any currently supported version. The status of versions can be viewed here:"[https://devguide.python.org/versions/ Status of Python versions]". It is recommended to use a version with "security" or "bugfix" status. Versions marked as "end-of-life" are not supported. Versions marked as "feature" are not recommended. If you have an unsupported version ("end-of-life") installed on your host, you should be sure to [[Python-update_EN|install additionally]] a more recent version of Python.''

* Stop the supervisor and all services under its control:
sudo systemctl stop supervisor

* The console script that runs various commands from the command line is now named <code>run</code> instead of <code>userside</code>. You need to change the launch command everywhere from <code>php /var/www/userside/userside</code> to <code>php /var/www/userside/run</code>.
** In the file /etc/cron.d/userside you need to replace the line:
* * * * * www-data /usr/bin/php /var/www/userside/userside cron > /dev/null
per line:
* * * * * www-data /usr/bin/php /var/www/userside/run cron > /dev/null
** In the file /etc/supervisor/conf.d/us-core-worker.conf you need to replace the line:
command=/usr/bin/php /var/www/userside/userside queue/listen
per line:
command=/usr/bin/php /var/www/userside/run queue/listen

* The RabbitMQ user used by USERSIDE needs to be given monitoring privileges so that USERSIDE can monitor the operation of the server. To do this, execute (assuming your user name is <code>userside</code>):
sudo rabbitmqctl set_user_tags "userside" "monitoring"
If you are using a vhost other than the root (default), you should also add the appropriate option, e.g. for vhost <code>copy</code>:
sudo rabbitmqctl --vhost copy set_user_tags "userside" "monitoring"

* Remove rudimentary queues:
<pre>
sudo rabbitmqctl delete_queue userside.core
sudo rabbitmqctl delete_queue userside.microservice.poller
</pre>

* Use the automatic [[Installer|installer]] to perform an [[Upgrade|upgrade]]:
sudo -u www-data php userside_install.phar install

* The following action only needs to be performed if you [[Python-update_EN| updated Python]]. If you haven't updated, you don't need to do it:
sudo rm -rf /var/www/userside/microservice/poller/venv
sudo python3.11 -m venv /var/www/userside/microservice/poller/venv

* It is necessary to update (install) the dependencies for poller:
cd /var/www/userside/microservice/poller
sudo venv/bin/pip3 install --upgrade pip
sudo venv/bin/pip3 install -U -r requirements.txt

* Note that as of version 3.18, background services do much of the work of interacting with network hardware. Start the supervisor:
sudo systemctl start supervisor
And make sure that all services start and run correctly (RUNNING):
sudo supervisorctl status
You should see 5 instances of the us-poller service and 10 instances of the us-core-worker service, or the number you have specified yourself in the supervisor configuration files.

* As of version 3.18, instead of satellite modules (usm_satellite) installed on remote nodes to proxy hardware communication commands, the exact same pollers are now used as in the system kernel, but with the mandatory "setellite" identifier in the settings. Be sure to review the steps required to switch from usm_satellite to usm_poller [[Satellites|in the appropriate section]].

* In version 3.18, we've reworked the database structure a lot. Both the basic schema and the names of all tables, almost all fields and, often, the types of these fields have changed. Firstly, updating can take a long time, and secondly, if you used direct reading from the database - all this needs to be reworked.

* Reworked low-level hardware polling ''(FDB, ARP, interface polling, etc)''. All of this is now done by kernel pollers. After the update, check if FDB tables and other polling works.

* Customers' labels are combined with common labels in the system. Accordingly, in the configuration files of billing interaction modules (or in the API) it is required to change the IDs of labels to new ones (if you use it). For example, for the usm_utm5 module this is the $markMerge variable

* Removed JABBER interaction. Use the "Custom HTTP request" notification service or Messenger ''(Telegram)''.

* If you have not yet reconfigured the [[UserSide_API_Key_EN| to the new system]] - do so. In version 3.18, $zapikey is removed and the API key will stop working for those who have not reconfigured.

* If in version 3.17 you still haven't [[Upgrade 3.17|configured WebSTOMP]], you need to do so or parts of the system will stop working

* Don't forget to update all modules to their latest versions

* In the poller (usm_poller), which is now used to interact with the hardware, one community is used for authentication in SNMP v1 and v2. But in the USERSIDE user interface, two fields (ro and rw) are left for now for backward compatibility. Which of the values will be used is described below in the algorithm for selecting a single SNMP-community. To simplify this for you, you can use the same community for the two fields. For example, if you want to give Userside read-only access, then enter the read-only community in both fields (ro and rw). If you want to grant full access, then also enter the same community with full permissions in both fields. It is also worth considering that the blank field will be filled in from the global Userside settings.

[[File:Snmp_community_select_en.png|frame|centre]]

'''List of Changes:''' [[3.18_EN|view]]

'''Performing the upgrade:''' [[Upgrade|instruction]]

Upgrade 3.19

2025-07-08T11:33:54Z

Uscld2:

[[Upgrade_3.19|en]] | [[Обновление_3.19|ru]]

Version: '''[[3.19_EN|3.19]]'''

Version required: '''[[3.12_EN|3.12]] and above'''

== A few words from the author ==
* In version 3.19 we have done a lot to universalise and customise the system. Now every customer can switch off unused sections, create and operate completely arbitrary sections and entities, and change the naming of basic terms such as "Customers".

* Now we have "[[Two-Factor Authentication (2FA)]]". Don't neglect security and use it.

* Most files in the userside web directory have, for security reasons, changed their location several levels up and are now inaccessible via the web. Also changed the name of the directory that should be the root directory for the web to the default name public.

* System page/link routing has been changed
<pre>
It was: /?core_section=customer&action=show&id=1234
It became: /customer/1234
</pre>

* In version 3.19, the sections are declared obsolete:
** "Layout of construction lengths and assembled couplings for cable line routes". In version 3.20 the section will be removed
** "[[Unknown MAC-addresses]]". In version 3.20 the section will be removed
** "Technical support interface". In version 3.20 the section will be removed

* [[Upgrade]]. '''Recommended to have two instances of the system'''. A separate operational one and a separate test one. On the test one you can periodically update the database from the operational system and perform updates to make sure that everything is working, familiarise yourself with innovations or identify things that have stopped working for you.

* Our Telegram group for mutual communication of clients with each other: https://t.me/usersideeu and the news channel: https://t.me/userside

== Specifics in performing the upgrade ==

When upgrading in a Docker environment, refer to the [https://github.com/userside/userside-docker/tree/v3.18 instructions] in the Docker bundle repository.

* If you are upgrading from a version 3.10 - check out the page: [[Upgrade 3.11]]

* If you are upgrading from a version 3.11 and before - check out the page: [[Upgrade 3.12]]

* If you are upgrading from a version 3.12 and before - check out the page: [[Upgrade 3.13]]

* If you are upgrading from a version 3.13 and before - check out the page: [[Upgrade 3.14]]

* If you are upgrading from a version 3.14 and before - check out the page: [[Upgrade 3.15]]

* If you are upgrading from a version 3.15 and before - check out the page: [[Upgrade 3.16]]

* If you are upgrading from a version 3.16 and before - check out the page: [[Upgrade 3.17]]

* If you are upgrading from a version 3.17 and before - check out the page: [[Upgrade 3.18]]

* Move/remove extraneous files, directories, etc. from the userside directory (/var/www/userside). Only distribution files of the system itself and files that the system creates during its operation should be there. Userside modules (usm) should not be stored there either. Use separate directories for them (e.g. /opt/userside). Extraneous files in the userside directory can be removed during the upgrade process.

* Save the userside3/main/config/custom_api.php and userside3/main/skins/user_style.css ''(if any)'' files. These can come in handy in case of update errors and deleting them when doing so.

* Most files in the userside web directory have, for security reasons, changed their location several levels up and are now inaccessible via the web.

* Version 3.19 requires PHP version 8.3. You can install all the necessary packages in addition to your existing different PHP version. If you are using LDAP, also install php8.3-ldap. If you are using TurboSMS, install php8.3-soap.
sudo apt install -y php8.3-{fpm,cli,common,curl,intl,mbstring,opcache,pgsql,readline,xml,zip,snmp,gd}

* If php8.3 is not in your repository, use an alternative repository such as deb.sury.org by adding it to your system as follows and then repeating the PHP8.3 installation command above:
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

* Change the PHP configuration as follows and restart the php-fpm service.
<pre>
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@max_input_time.*@max_input_time = 300@" /etc/php/8.3/fpm/php.ini

sudo systemctl restart php8.3-fpm
</pre>

* create a new public directory inside the userside directory (if you have it installed elsewhere, edit the command before executing):
<pre>
sudo mkdir -p /var/www/userside/public
</pre>

* In the NGINX server configuration (/etc/nginx/conf.d/userside.conf), change the paths to the root directory. The line:
<pre>
root /var/www/userside/userside3;
</pre>
Replace it with:
<pre>
root /var/www/userside/public;
</pre>
* Also change there <code>location /</code> in its entirety for the next:
<pre>
location / {
try_files $uri $uri/ /index.php$is_args$args;
}
</pre>
* Also there for <code>location ~ \.php$</code> change the value for fastcgi_pass from:
fastcgi_pass unix:/run/php/php8.1-fpm.sock;
to
fastcgi_pass unix:/run/php/php8.3-fpm.sock;
and reread the nginx configuration:
sudo nginx -s reload

* For the websocket-user (websock-user) of the RabbitMQ broker, you need to change the permissions as follows:
<pre>
sudo rabbitmqctl set_permissions -p "/" "websock-user" "^erp-stomp:id-.*" "" "^erp-stomp:id-.*"
</pre>
If your websocket-user name is different from websock-user, specify it instead of websock-user in the above commands.

* Note that when you invoke the command <code>php</code> from the command line, php8.3 will now be invoked, since it is the latest version installed. If you're still using php8.1 anywhere, you'll need to change the php call in those places or change the alternate php command to run the version you want.

* USERSIDE 3.19 ''requires Python3 of any currently supported version. The status of versions can be viewed here:"[https://devguide.python.org/versions/ Status of Python versions]". It is recommended to use a version with "security" or "bugfix" status. Versions marked as "end-of-life" are not supported. Versions marked as "feature" are not recommended. If you have an unsupported version ("end-of-life") installed on your host, you should be sure to [[Python-update_EN|install additionally]] a more recent version of Python.''

* Use the automatic [[Installer|installer]] to perform [[Upgrade|upgrade]]:
sudo -u www-data php userside_install.phar install

* The following action only needs to be performed if you [[Python-update EN| updated Python]]. If you haven't updated, you don't need to do it:
<pre>
cd /var/www/userside/microservice/poller
sudo rm -rf venv
sudo python3.11 -m venv venv
</pre>

* You need to update (install) the dependencies for poller:
<pre>
cd /var/www/userside/microservice/poller
sudo venv/bin/pip install --upgrade pip
sudo venv/bin/pip install -U -r requirements.txt
</pre>

* And restart the services
<pre>
sudo supervisorctl restart all
</pre>

* Redesigned low-level interrogation of equipment ''(PON, TDR)''.

* The system of two SNMP-communities is replaced by one SNMP-community. This one SNMP-community will be the one that was specified in the rw-community field. If the rw-community field was empty - the value of the ro-community field will be used

* Don't forget to upgrade all modules to their latest versions

* If you are using the [[Usm_pon_EN|usm_pon]] module - reconfigure it to run at the required frequency in system cron, depending on how many OLTs you have. The module now polls only one device per run ''(previously all devices were polled simultaneously without the ability to mitigate load and skip unnecessary devices)''. Devices will be polled one at a time. At each startup, the next device with polling enabled will be polled.

* You can now configure separate notification templates for different types of tasks. Check your existing templates for correct migrations.

'''List of changes:''' [[3.19_EN|view]]

'''Performing an upgrade:''' [[Upgrade|instruction]]

Upgrade 3.19

2025-07-08T11:33:43Z

Uscld2:

[[Upgrade_3.19|en]] | [[Обновление_3.19|ru]]

Version: '''[[3.19_EN|3.19]]'''

Version required: '''[[3.19_EN|3.12]] and above'''

== A few words from the author ==
* In version 3.19 we have done a lot to universalise and customise the system. Now every customer can switch off unused sections, create and operate completely arbitrary sections and entities, and change the naming of basic terms such as "Customers".

* Now we have "[[Two-Factor Authentication (2FA)]]". Don't neglect security and use it.

* Most files in the userside web directory have, for security reasons, changed their location several levels up and are now inaccessible via the web. Also changed the name of the directory that should be the root directory for the web to the default name public.

* System page/link routing has been changed
<pre>
It was: /?core_section=customer&action=show&id=1234
It became: /customer/1234
</pre>

* In version 3.19, the sections are declared obsolete:
** "Layout of construction lengths and assembled couplings for cable line routes". In version 3.20 the section will be removed
** "[[Unknown MAC-addresses]]". In version 3.20 the section will be removed
** "Technical support interface". In version 3.20 the section will be removed

* [[Upgrade]]. '''Recommended to have two instances of the system'''. A separate operational one and a separate test one. On the test one you can periodically update the database from the operational system and perform updates to make sure that everything is working, familiarise yourself with innovations or identify things that have stopped working for you.

* Our Telegram group for mutual communication of clients with each other: https://t.me/usersideeu and the news channel: https://t.me/userside

== Specifics in performing the upgrade ==

When upgrading in a Docker environment, refer to the [https://github.com/userside/userside-docker/tree/v3.18 instructions] in the Docker bundle repository.

* If you are upgrading from a version 3.10 - check out the page: [[Upgrade 3.11]]

* If you are upgrading from a version 3.11 and before - check out the page: [[Upgrade 3.12]]

* If you are upgrading from a version 3.12 and before - check out the page: [[Upgrade 3.13]]

* If you are upgrading from a version 3.13 and before - check out the page: [[Upgrade 3.14]]

* If you are upgrading from a version 3.14 and before - check out the page: [[Upgrade 3.15]]

* If you are upgrading from a version 3.15 and before - check out the page: [[Upgrade 3.16]]

* If you are upgrading from a version 3.16 and before - check out the page: [[Upgrade 3.17]]

* If you are upgrading from a version 3.17 and before - check out the page: [[Upgrade 3.18]]

* Move/remove extraneous files, directories, etc. from the userside directory (/var/www/userside). Only distribution files of the system itself and files that the system creates during its operation should be there. Userside modules (usm) should not be stored there either. Use separate directories for them (e.g. /opt/userside). Extraneous files in the userside directory can be removed during the upgrade process.

* Save the userside3/main/config/custom_api.php and userside3/main/skins/user_style.css ''(if any)'' files. These can come in handy in case of update errors and deleting them when doing so.

* Most files in the userside web directory have, for security reasons, changed their location several levels up and are now inaccessible via the web.

* Version 3.19 requires PHP version 8.3. You can install all the necessary packages in addition to your existing different PHP version. If you are using LDAP, also install php8.3-ldap. If you are using TurboSMS, install php8.3-soap.
sudo apt install -y php8.3-{fpm,cli,common,curl,intl,mbstring,opcache,pgsql,readline,xml,zip,snmp,gd}

* If php8.3 is not in your repository, use an alternative repository such as deb.sury.org by adding it to your system as follows and then repeating the PHP8.3 installation command above:
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

* Change the PHP configuration as follows and restart the php-fpm service.
<pre>
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@max_input_time.*@max_input_time = 300@" /etc/php/8.3/fpm/php.ini

sudo systemctl restart php8.3-fpm
</pre>

* create a new public directory inside the userside directory (if you have it installed elsewhere, edit the command before executing):
<pre>
sudo mkdir -p /var/www/userside/public
</pre>

* In the NGINX server configuration (/etc/nginx/conf.d/userside.conf), change the paths to the root directory. The line:
<pre>
root /var/www/userside/userside3;
</pre>
Replace it with:
<pre>
root /var/www/userside/public;
</pre>
* Also change there <code>location /</code> in its entirety for the next:
<pre>
location / {
try_files $uri $uri/ /index.php$is_args$args;
}
</pre>
* Also there for <code>location ~ \.php$</code> change the value for fastcgi_pass from:
fastcgi_pass unix:/run/php/php8.1-fpm.sock;
to
fastcgi_pass unix:/run/php/php8.3-fpm.sock;
and reread the nginx configuration:
sudo nginx -s reload

* For the websocket-user (websock-user) of the RabbitMQ broker, you need to change the permissions as follows:
<pre>
sudo rabbitmqctl set_permissions -p "/" "websock-user" "^erp-stomp:id-.*" "" "^erp-stomp:id-.*"
</pre>
If your websocket-user name is different from websock-user, specify it instead of websock-user in the above commands.

* Note that when you invoke the command <code>php</code> from the command line, php8.3 will now be invoked, since it is the latest version installed. If you're still using php8.1 anywhere, you'll need to change the php call in those places or change the alternate php command to run the version you want.

* USERSIDE 3.19 ''requires Python3 of any currently supported version. The status of versions can be viewed here:"[https://devguide.python.org/versions/ Status of Python versions]". It is recommended to use a version with "security" or "bugfix" status. Versions marked as "end-of-life" are not supported. Versions marked as "feature" are not recommended. If you have an unsupported version ("end-of-life") installed on your host, you should be sure to [[Python-update_EN|install additionally]] a more recent version of Python.''

* Use the automatic [[Installer|installer]] to perform [[Upgrade|upgrade]]:
sudo -u www-data php userside_install.phar install

* The following action only needs to be performed if you [[Python-update EN| updated Python]]. If you haven't updated, you don't need to do it:
<pre>
cd /var/www/userside/microservice/poller
sudo rm -rf venv
sudo python3.11 -m venv venv
</pre>

* You need to update (install) the dependencies for poller:
<pre>
cd /var/www/userside/microservice/poller
sudo venv/bin/pip install --upgrade pip
sudo venv/bin/pip install -U -r requirements.txt
</pre>

* And restart the services
<pre>
sudo supervisorctl restart all
</pre>

* Redesigned low-level interrogation of equipment ''(PON, TDR)''.

* The system of two SNMP-communities is replaced by one SNMP-community. This one SNMP-community will be the one that was specified in the rw-community field. If the rw-community field was empty - the value of the ro-community field will be used

* Don't forget to upgrade all modules to their latest versions

* If you are using the [[Usm_pon_EN|usm_pon]] module - reconfigure it to run at the required frequency in system cron, depending on how many OLTs you have. The module now polls only one device per run ''(previously all devices were polled simultaneously without the ability to mitigate load and skip unnecessary devices)''. Devices will be polled one at a time. At each startup, the next device with polling enabled will be polled.

* You can now configure separate notification templates for different types of tasks. Check your existing templates for correct migrations.

'''List of changes:''' [[3.19_EN|view]]

'''Performing an upgrade:''' [[Upgrade|instruction]]

Обновление 3.19

2025-07-08T11:33:34Z

Uscld2:

[[Upgrade_3.19|en]] | [[Обновление_3.19|ru]]

Версия: '''[[3.19]]'''

Требуется версия: '''[[3.12]] и выше'''

== Несколько слов от автора ==
* В версии 3.19 мы очень много сделали для универсализации и индивидуализации системы. Теперь каждый клиент может отключить неиспользуемые разделы, создать совершенно произвольные разделы и сущности и оперировать ими, а также изменять наименование базовых терминов - таких как "Абоненты"

* У нас появилась "[[Двухфакторная аутентификация (2FA)]]". Не пренебрегайте безопасностью и используйте её.

* Большинство файлов из веб-директории userside с целью безопасности изменили своё местоположение на несколько уровней выше и теперь недоступны через веб. Также изменилось имя каталога, который должен быть корневым для web, на стандартное имя public.

* Изменена маршрутизация страниц/ссылок системы
<pre>
Было: /?core_section=customer&action=show&id=1234
Стало: /customer/1234
</pre>

* В версии 3.19 объявляются устаревшими разделы:
** "Схема размещения строительных длин и смонтированных муфт для трасс кабельных линий". В версии 3.20 раздел будет удалён
** "[[Неизвестные MAC-адреса]]". В версии 3.20 раздел будет удалён
** "Интерфейс технической поддержки". В версии 3.20 раздел будет удалён

* [[Обновление]]. '''Рекомендую иметь два инстанса системы'''. Отдельно действующую и отдельно тестовую. На тестовой вы можете периодически обновлять базу данных с действующей системы и проводить обновление, убеждаясь, что всё работает, ознакомиться с нововведениями или выявлять моменты, которые у вас перестали работать.

* Наша группа в Telegram для взаимного общения клиентов между собой: https://t.me/usersideeu и канал для новостей: https://t.me/userside

== Особенности в проведении обновления ==

При обновлении в Docker-окружении, обратитесь к [https://github.com/userside/userside-docker/tree/v3.18 инструкциям] в репозитории Docker-бандла.

* Если вы обновляетесь с версии 3.10 - ознакомьтесь со страницей: [[Обновление 3.11]]

* Если вы обновляетесь с версии 3.11 и ранее - ознакомьтесь со страницей: [[Обновление 3.12]]

* Если вы обновляетесь с версии 3.12 и ранее - ознакомьтесь со страницей: [[Обновление 3.13]]

* Если вы обновляетесь с версии 3.13 и ранее - ознакомьтесь со страницей: [[Обновление 3.14]]

* Если вы обновляетесь с версии 3.14 и ранее - ознакомьтесь со страницей: [[Обновление 3.15]]

* Если вы обновляетесь с версии 3.15 и ранее - ознакомьтесь со страницей: [[Обновление 3.16]]

* Если вы обновляетесь с версии 3.16 и ранее - ознакомьтесь со страницей: [[Обновление 3.17]]

* Если вы обновляетесь с версии 3.17 и ранее - ознакомьтесь со страницей: [[Обновление 3.18]]

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

* Сохраните файлы ''(при их наличии)''
userside3/main/config/custom_api.php
userside3/main/skins/user_style.css
userside3/main/js/user_script.js

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

* Большинство файлов из веб-директории userside с целью безопасности изменили своё местоположение на несколько уровней выше и теперь недоступны через веб.

* Версия 3.19 требует PHP версии 8.3. Вы можете установить все необходимые пакеты дополнительно к уже существующей иной версии PHP. Если используете LDAP, то установите также php8.3-ldap. Если используете TurboSMS, то установите php8.3-soap.
sudo apt install -y php8.3-{fpm,cli,common,curl,intl,mbstring,opcache,pgsql,readline,xml,zip,snmp,gd}

* Если версия php8.3 отсутствует в вашем репозитории, то воспользуйтесь альтернативным репозиторием, например, deb.sury.org, добавив его в систему следующим образом и затем повторив команду установки PHP8.3 приведенную пунктом выше:
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

* Измените конфигурацию PHP следующим образом и перезапустите службу php-fpm.
<pre>
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@max_input_time.*@max_input_time = 300@" /etc/php/8.3/fpm/php.ini

sudo systemctl restart php8.3-fpm
</pre>

* создайте новый каталог public внутри каталога userside (если у вас установлено в другом месте, отредактируйте команду перед выполнением):
<pre>
sudo mkdir -p /var/www/userside/public
</pre>

* В настройке NGINX-сервера (/etc/nginx/conf.d/userside.conf) измените пути к корневому каталогу. Строку:
<pre>
root /var/www/userside/userside3;
</pre>
Замените на:
<pre>
root /var/www/userside/public;
</pre>
* Там же измените <code>location /</code> целиком на следующий:
<pre>
location / {
try_files $uri $uri/ /index.php$is_args$args;
}
</pre>
* Там же для <code>location ~ \.php$</code> измените значение для fastcgi_pass с:
fastcgi_pass unix:/run/php/php8.1-fpm.sock;
на
fastcgi_pass unix:/run/php/php8.3-fpm.sock;
и перечитайте конфигурацию nginx:
sudo nginx -s reload

* Для websocket-пользователя (websock-user) брокера RabbitMQ необходимо изменить разрешения следующим образом:
<pre>
sudo rabbitmqctl set_permissions -p "/" "websock-user" "^erp-stomp:id-.*" "" "^erp-stomp:id-.*"
</pre>
Если имя вашего websocket-пользователя отличается от websock-user, то укажите его вместо websock-user в приведенных выше командах.

* Обратите внимание, что при вызове команды <code>php</code> из командной строки, теперь будет вызываться php8.3, так как это последняя установленная версия. Если вы где-либо до сих пор используете php8.1, то вам нужно изменить вызов php в этих местах либо изменить альтернативную команду php, чтобы она запускала нужную вам версию.

* USERSIDE 3.19 ''требует Python3 любой поддерживаемой на данный момент версии. Статус версий можно посмотреть здесь: "[https://devguide.python.org/versions/ Status of Python versions]". Рекомендуется использовать версию с состоянием "security" или "bugfix". Версии отмеченные как "end-of-life" не поддерживаются. Отмеченные как "feature" не рекомендуется использовать. Если у вас на хосте неподдерживаемая версия ("end-of-life"), то нужно обязательно [[Python-update|установить дополнительно]] более свежую версию Python.''

* С помощью автоматического [[Инсталлятор|инсталлятора]] выполните [[Обновление|обновление]]:
sudo -u www-data php userside_install.phar install

* Следующее действие нужно выполнять только если вы [[Python-update|обновили Python]]. Если не обновляли, можно не выполнять:
<pre>
cd /var/www/userside/microservice/poller
sudo rm -rf venv
sudo python3.11 -m venv venv
</pre>

* Необходимо обновить (установить) зависимости для поллера:
<pre>
cd /var/www/userside/microservice/poller
sudo venv/bin/pip install --upgrade pip
sudo venv/bin/pip install -U -r requirements.txt
</pre>

* И перезапустить службы
<pre>
sudo supervisorctl restart all
</pre>

* Переработан низкоуровневый опрос оборудования ''(PON, TDR)''.

* Система двух SNMP-community заменена на один SNMP-community. Этим одним SNMP-community будет то, которое было указано в поле rw-community. Если поле rw-community было пустое - то будет использовано значение поля ro-community

* Не забудьте обновить все модули на их свежие версии

* Если вы используете модуль [[usm_pon]] - перенастройте в системном cron его запуск на нужную частоту в зависимости от количества у вас OLT. Теперь модуль опрашивает только одно устройство за запуск ''(ранее опрашивались все устройства одновременно без возможности смягчения нагрузки и пропуска ненужных устройств)''. Устройства будут опрашиваться по очереди. При каждом запуске на опрос будет подаваться следующее устройство у которого включен такой опрос.

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

'''Список изменений:''' [[3.19|просмотреть]]

'''Проведение обновления:''' [[Обновление|инструкция]]

Обновление 3.20

2025-07-08T11:33:10Z

Uscld2:

[[Upgrade_3.20|en]] | [[Обновление_3.20|ru]]

Версия: '''[[3.20]]'''

Требуется версия: '''[[3.12]] и выше'''

== Несколько слов от автора ==
* Версию 3.19 мы дорабатывали динамически. Добавляли в рабочем порядке как небольшие возможности так и крупные доработки. Цель - чтоб клиенты не ждали год новую версию и новые востребованные функции, а пользовались ими уже сейчас. Соответственно почти все изменения, что указаны как доработки версии 3.20 - они постепенно становились доступны для версии 3.19. Скажем версия 3.19.54 мало чем отличается от версии 3.20.0. Строго говоря нововведения версии 3.20.0 - это те моменты на которые мы хотели обратить внимание по сравнению с версией 3.19.0.

* Таким образом обновление с 3.19 на 3.20 "бесшовное" и ничем особо не отличается от обновления скажем с 3.19.52 на 3.19.53. Дополнительных библиотек/модулей устанавливать не требуется

* [[Лимиты объектов|Убран лимит]] на количество адресных объектов ''(здания, улицы, населенные пункты)''

* В версии 3.20 удалены разделы:
** "Схема размещения строительных длин и смонтированных муфт для трасс кабельных линий"
** "[[Неизвестные MAC-адреса]]"
** "Интерфейс технической поддержки"

* [[Обновление]]. '''Рекомендую иметь два инстанса системы'''. Отдельно действующую и отдельно тестовую. На тестовой вы можете периодически обновлять базу данных с действующей системы и проводить обновление, убеждаясь, что всё работает, ознакомиться с нововведениями или выявлять моменты, которые у вас перестали работать.

* Наша группа в Telegram для взаимного общения клиентов между собой: https://t.me/usersideeu и канал для новостей: https://t.me/userside

== Особенности в проведении обновления ==

При обновлении в Docker-окружении, обратитесь к [https://github.com/userside/userside-docker/tree/v3.18 инструкциям] в репозитории Docker-бандла.

* Если вы обновляетесь с версии 3.10 - ознакомьтесь со страницей: [[Обновление 3.11]]

* Если вы обновляетесь с версии 3.11 и ранее - ознакомьтесь со страницей: [[Обновление 3.12]]

* Если вы обновляетесь с версии 3.12 и ранее - ознакомьтесь со страницей: [[Обновление 3.13]]

* Если вы обновляетесь с версии 3.13 и ранее - ознакомьтесь со страницей: [[Обновление 3.14]]

* Если вы обновляетесь с версии 3.14 и ранее - ознакомьтесь со страницей: [[Обновление 3.15]]

* Если вы обновляетесь с версии 3.15 и ранее - ознакомьтесь со страницей: [[Обновление 3.16]]

* Если вы обновляетесь с версии 3.16 и ранее - ознакомьтесь со страницей: [[Обновление 3.17]]

* Если вы обновляетесь с версии 3.17 и ранее - ознакомьтесь со страницей: [[Обновление 3.18]]

* Если вы обновляетесь с версии 3.18 и ранее - ознакомьтесь со страницей: [[Обновление 3.19]]

* Перенесите/удалите посторонние файлы, каталоги и прочее из директории userside. Там должны находится только дистрибутивные файлы самой системы и файлы, которые система создает во время своей работы. Модули userside (usm) также не должны там хранится. Используйте отдельные каталоги для них (например, /opt/userside). Посторонние файлы из директории userside могут быть удалены в процессе обновления

* С помощью автоматического [[Инсталлятор|инсталлятора]] выполните [[Обновление|обновление]]:
sudo -u www-data php userside_install.phar install

* Не забудьте обновить все модули на их свежие версии

'''Список изменений:''' [[3.20|просмотреть]]

'''Проведение обновления:''' [[Обновление|инструкция]]

Установка

2025-06-20T10:06:39Z

Uscld2:

<languages/>
[[Installation|en]] | [[Установка|ru]]

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

== Описание ==
В целях упрощения будут рассмотрены команды для операционной системы '''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 любой поддерживаемой на данный момент версии. Статус версий можно посмотреть здесь: "[https://devguide.python.org/versions/ 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 - <code>/var/www/userside</code>. Внутри этого каталога должен быть подкаталог 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. Вы можете копировать строки по одной и вставлять их в командную строку вашей операционной системы.

Следующие строки скопируйте и вставьте целиком:
<pre>
sudo tee /etc/apt/sources.list.d/contrib-non-free.list << EOL
deb http://deb.debian.org/debian/ $(lsb_release -sc) contrib non-free non-free-firmware
EOL

sudo apt update
sudo apt full-upgrade -y
sudo apt install -y gnupg ca-certificates lsb-release debian-archive-keyring debian-keyring libsnmp-dev snmp-mibs-downloader
</pre>

=== PostgreSQL ===
==== Альтернативный официальный репозиторий ====
Мы настоятельно рекомендуем использовать последнюю версию PostgreSQL, так как это всегда положительно сказывается на скорости работы. Добавьте в систему официальный репозиторий Postgres:
<pre>
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
</pre>
Если у вас другая операционная система, вы можете найти необходимые команды для нее на [https://www.postgresql.org/download/ официальном сайте 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
<pre>
sudo -u postgres createuser userside -P
sudo -u postgres createdb -e -E "UTF-8" -l "uk_UA.UTF-8" -O userside -T template0 userside
sudo -u postgres psql -d userside -c "CREATE EXTENSION postgis"
</pre>

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

=== 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):
<pre>
sudo systemctl restart redis
redis-cli -h 127.0.0.1 -p 6379 -a MYPASSWORDHERE ping
</pre>

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

==== Добавление альтернативных репозиториев ====
Следующий блок скопируйте и вставьте целиком в командную строку
<pre>
curl -1sLf https://dl.cloudsmith.io/public/rabbitmq/rabbitmq-erlang/gpg.E495BB49CC4BBE5B.key | sudo gpg --dearmor | sudo tee /usr/share/keyrings/rabbitmq-erlang-archive-keyring.gpg > /dev/null
curl -1sLf https://dl.cloudsmith.io/public/rabbitmq/rabbitmq-server/gpg.9F4587F226208342.key | sudo gpg --dearmor | sudo tee /usr/share/keyrings/rabbitmq-server-archive-keyring.gpg > /dev/null

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
</pre>

==== Установка ====
Убедитесь, что в /etc/hosts есть запись для имени вашего хоста. Отсутствие такрой записи (например, если вы изменили имя хоста после инсталляции) является основной ошибкой, возникающей при установке RabbitMQ. Так что лучше еще раз убедитесь, что запись соответствующая имени хосту имеется.
<pre>
sudo apt install -y erlang-base \
erlang-asn1 erlang-crypto erlang-eldap erlang-ftp erlang-inets \
erlang-mnesia erlang-os-mon erlang-parsetools erlang-public-key \
erlang-runtime-tools erlang-snmp erlang-ssl \
erlang-syntax-tools erlang-tftp erlang-tools erlang-xmerl

sudo apt install rabbitmq-server -y --fix-missing
</pre>

==== Установка необходимых дополнений ====
Следующие две строки выполняйте по одной за раз!
<pre>
sudo rabbitmq-plugins enable rabbitmq_management --offline

sudo rabbitmq-plugins enable rabbitmq_web_stomp --offline
</pre>

==== Настройка ====
Скопируйте и вставьте целиком следующий блок:
<pre>
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
</pre>

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

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

Создайте '''пользователя, от имени которого будут работать ERP USERSIDE''' и модули. Пример для имени пользователя '''userside''' (наделять админскими правами этого пользователя не нужно):
<pre>
sudo rabbitmqctl add_user "userside" "пароль_системы"
sudo rabbitmqctl set_user_tags "userside" "monitoring"
sudo rabbitmqctl set_permissions -p "/" "userside" ".*" ".*" ".*"
</pre>

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

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

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

Перезапустите службу rabbitmq:
<pre>
sudo systemctl restart rabbitmq-server
</pre>

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

По умолчанию WEB-интерфейс управления доступен по адресу http://userside.mycompany.com:15672. Рекомендуем использовать фаервол, чтобы ограничить доступ к этому интерфейсу управления.

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

=== PHP ===
==== Альтернативный репозиторий ====
<pre>
sudo curl -sSLo /usr/share/keyrings/deb.sury.org-php.gpg https://packages.sury.org/php/apt.gpg
sudo sh -c 'echo "deb [signed-by=/usr/share/keyrings/deb.sury.org-php.gpg] https://packages.sury.org/php/ $(lsb_release -sc) main" > /etc/apt/sources.list.d/php.list'
sudo apt update
</pre>

==== Установка ====
Выполните следующие команды:
<pre>
sudo apt install -y php8.3-{fpm,cli,common,curl,intl,mbstring,opcache,pgsql,readline,xml,zip,snmp,gd}
</pre>

Если вы планируете использовать LDAP, необходимо установить расширение php-ldap:
<pre>
sudo apt install -y php8.3-ldap
</pre>

Если вы планируете использовать отправку SMS используя TurboSMS, также понадобится расширение php-soap:
<pre>
sudo apt install -y php8.3-soap
</pre>

==== Настройка ====
Далее приведены команды, вносящие изменения в файлы конфигурации.
<pre>
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
</pre>

=== NGINX ===
==== Альтернативный официальный репозиторий ====
Версия NGINX, поставляемая в репозитории Debian, полностью подходит для использования и нет необходимости в добавлении альтернативного репозитория. Однако, если вам хочется всегда иметь последнюю версию, то выполните следующие строки, чтобы добавить в операционную систему официальный репозиторий nginx:
<pre>
curl https://nginx.org/keys/nginx_signing.key | gpg --dearmor \
| sudo tee /usr/share/keyrings/nginx-archive-keyring.gpg >/dev/null
echo "deb [signed-by=/usr/share/keyrings/nginx-archive-keyring.gpg] \
http://nginx.org/packages/debian `lsb_release -cs` nginx" \
| sudo tee /etc/apt/sources.list.d/nginx.list
echo -e "Package: *\nPin: origin nginx.org\nPin: release o=nginx\nPin-Priority: 900\n" \
| sudo tee /etc/apt/preferences.d/99nginx
sudo apt update
</pre>

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

==== Установка ====
<pre>
sudo apt install -y nginx
</pre>

==== Настройка ====
<pre>
sudo sed -i "s@^user.*;@user www-data www-data;@" "/etc/nginx/nginx.conf"
sudo systemctl restart nginx
</pre>

Следующий пример настройки подразумевает, что ERP USERSIDE будет установлен в стандартный каталог системы <code>/var/www/userside</code>. Если вы желаете установить ERP USERSIDE в другой каталог, пожалуйста, не забывайте исправлять его во всех последующих примерах. Чтобы не ошибиться, мы рекомендуем использовать именно каталог <code>/var/www/userside</code>.

Теперь отредактируйте файл /etc/nginx/conf.d/default.conf. Либо удалите его и создайте файл с именем /etc/nginx/conf.d/userside.conf. В любом случае, не зависимо от вашего выбора, содержимое файла должно быть следующим (вместо userside.mycompany.com укажите свое доменное имя):
<pre>
server {
listen 80 default_server;
server_name userside.mycompany.com;
charset utf-8;
client_max_body_size 100M;

access_log /var/log/nginx/userside-access.log;
error_log /var/log/nginx/userside-error.log;

root /var/www/userside/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|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; }
}
</pre>

Также, возможно, вы захотите настроить SSL и что-либо еще. Эта тема выходит за рамки данной инстуркции.

Если Вы установили RabbitMQ '''на другом сервере''', либо изменили значение порта WebSTOMP с 15674 на какой-то другой, то укажите IP-адрес сервера с RabbitMQ и номер порта в строке <code>proxy_pass http://127.0.0.1:15674/ws;</code>. Протокол должен оставаться http. Путь должен оставаться /ws.

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

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

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

==== Установка необходимых пакетов ====
sudo apt install -y python3-dev python3-pip python3-venv libffi-dev pkg-config

=== Supervisor ===
sudo apt install -y supervisor

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

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

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

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

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

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

Вы можете ввести любой доступный вам номер версии 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). Выполните команды:
<pre>
sudo cp etc/us-core-worker.conf-example /etc/supervisor/conf.d/us-core-worker.conf
sudo cp microservice/poller/etc/usm_poller.conf-example /etc/supervisor/conf.d/usm_poller.conf
sudo cp etc/logrotate-example /etc/logrotate.d/userside
sudo cp microservice/poller/etc/logrotate-example /etc/logrotate.d/usm_poller
sudo cp etc/crontab-example /etc/cron.d/userside
</pre>

=== Установка необходимых зависимостей для usm_poller ===
Создайте виртуальное окружение venv для python и установите зависимые модули, как показано далее:
<pre>
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
</pre>

=== Запуск супервизора ===
Супервизор контролирует работу служб, указанных в его конфигурации. Для запуска супервизора выполните:
<pre>
sudo systemctl restart supervisor
</pre>
После запуска супервизора, спустя несколько секунд можно понаблюдать за состоянием всех контролируемых им служб. Все службы должны быть в состоянии RUNNING:
<pre>
sudo supervisorctl status
</pre>

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

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

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

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

==== Процесс обновления ====
Мы настоятельно рекомендуем выполнять тестовые обновления на [[HOWTO:_Клонирование_USERSIDE|копии системы]].

Для проведения обновления запустите инсталлятор в режиме install и следуйте инструкциям:
<pre>
cd /var/www/userside
sudo -u www-data php userside_install.phar install
</pre>

После обновления USERSIDE нужно обязательно обновить зависимости usm_poller:
<pre>
cd /var/www/userside/microservice/poller
sudo -H venv/bin/pip install -U pip
sudo -H venv/bin/pip install -U -r requirements.txt
</pre>

Теперь нужно перезапустить все службы, которолируемые супервизором и проследить чтобы все они запустились и были в состоянии RUNNING:
<pre>
sudo supervisorctl restart all
sudo supervisorctl status
</pre>

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

=== Резервное копирование ===
Установите периодическое резервное копирование базы данных и пользовательских файлов. Желательно минимум раз в сутки в моменты наименьшей нагрузки на сервер. В PostgreSQL существует два способа создать резервную копию базы данных: dump и sql-script. У каждого из них есть свои преимущества и недостатки. Первый создает безопасный дамп базы данных целиком, а второй создает SQL-скрипт, выполняя который можно восстановить как структуру так и данные. Рекомендуем обратиться к [https://www.postgresql.org/docs/current/app-pgdump.html документации по использованию команды pg_dump] для выбора более подходящего для вас способа или набора параметров.

Ниже приведены две команды для создания резервной копии базы данных — выбирайте одну из них и добавляйте в ваш crontab:
<pre>
# 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
</pre>

Для создания минимальной резервной копии '''файлов''' можно использовать следующую команду (для версии 3.15 и новее):
sudo tar -czf /backup/userside.tgz .env common/config/settings.json var/attachments
Этих файлов вместе с базой данных будет достаточно для восстановления работы USERSIDE. Но вы можете выполнять резервное копирование всего каталога /var/www/userside для большей надежности.

=== Восстановление из резервной копии ===
Для восстановления из дампа используется команда pg_restore. [https://postgrespro.ru/docs/postgresql/13/app-pgrestore Документация по использованию pg_restore]. Для восстановления из SQL-скрипта используется утилита psql. [https://www.postgresql.org/docs/current/app-psql.html Документация по использованию psql].

Перед восстановлением базы данных из резервной копии нужно обязательно остановить работу USERSIDE.

1. Остановить cron userside и всех модулей
<pre>
mkdir -p ~/cron
sudo mv /etc/cron.d/userside ~/cron
sudo mv /etc/cron.d/userside-modules ~/cron
</pre>
2. Остановить работу фоновых служб
<pre>
sudo supervisorctl stop all
</pre>
3. Остановить работу php-fpm
<pre>
sudo systemctl stop php8.3-fpm
</pre>
Только после этого можно приступать к восстановлению базы данных из резервной копии.

==== SQL-script ====
Для восстановления БД из резервной копии в виде SQL-скрипта, сначала нужно пересоздать базу данных, а затем восстановить в пустую базу данных резервную копию:
<pre>
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
</pre>

==== DUMP ====
Дамп содержит целиком базу данных со всеми ее элементами. Поэтому перед восстановлением базы данных из дампа её не должно существовать на сервере — удалите базу данных перед восстановлением из дампа. Также важно, чтобы пользователь базы данных (владелец всех элементов) уже существовал — создайте его перед восстановлением, если вы восстанавливаете базу данных на новом сервере, где нужного пользователя еще нет.

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

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

==== После восстановления базы данных ====
После восстановления базы данных любым способом, необходимо очистить кэш ERP USERSIDE, т.к. в кэше теперь находятся данные, отличные от данных в базе. Перейтите в каталог /var/www/userside и выполните команду очистки кэша (первую, если используется пароль или вторую, если не используется):
<pre>
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
</pre>
Восстановите работу служб, которые были остановлены перед выполнением резервной копии:
<pre>
sudo mv ~/cron/* /etc/cron.d
sudo supervisorctl start all
sudo systemctl start php8.3-fpm
</pre>
Выполните команду восстановления, чтобы файлы системы соответствовали версии базы данных и проверить систему на целостность файлов.
<pre>
cd /var/www/userside
sudo -u www-data php userside_install.phar repair
</pre>

HOWTO: USERSIDE cloning

2025-05-30T07:04:46Z

Uscld2:

[[HOWTO:_USERSIDE_cloning|en]] | [[HOWTO:_Клонирование_USERSIDE|ru]]

== Copy of system for testing or research ==

If you need to make a copy of the system to try out the new version before the actual upgrade, or to do anything else, there are a few simple steps to follow:

* copy the application files
cd /var/www/
sudo cp -r userside userside-copy

* configure the web server to work with the copy - copy the configuration file, edit and re-read the nginx configuration:
sudo cp /etc/nginx/conf.d/userside.conf /etc/nginx/conf.d/userside-copy.conf
sudo sed -i "s@/var/www/userside/userside3@/var/www/userside-copy/userside3@" "/etc/nginx/conf.d/userside-copy.conf"
sudo sed -i "s@/var/log/nginx/userside@/var/log/nginx/userside-copy@" "/etc/nginx/conf.d/userside-copy.conf"
sudo sed -i "s@старое.доменное.имя@новое.доменное.имя@" "/etc/nginx/conf.d/userside-copy.conf"
sudo systemctl reload nginx

* Copy the database (or create a new database and restore it from a backup):
sudo -u postgres createdb -e --encoding="UTF-8" --locale="ru_RU.UTF-8" --owner=userside --template=userside userside_copy
If you are copying the database to another server, you will need to create a role, necessarily the same as in the dump, before restoring it:
sudo -u postgres createuser userside -P

* In version 3.13 and newer, go to the directory with the new copy, edit the environment variables in the .env file so that they work with the new database and with the other (free) redis database (in the main installation you probably have the redis database number 0; you can use the other 15 available by default). Variables are responsible for this:
US_URL=http://new.domain.name
US_DB_DSN=pgsql:host=localhost;dbname=userside_copy;port=5432
US_REDIS_DB=1

* For versions up to 3.13, edit the database connection parameters in common/config/db.php and the URL in userside3/main/config/config.php

* In version 3.16 and newer you need to create an additional vhost for RabbitMQ, and then specify it in the .env file for the '''US_AMQP_DSN''' variable. The example below uses '''copy''' as the name of the new vhost (change to something more convenient for you if necessary). First run the command that creates the vhost, then add permissions for users within that vhost:
sudo rabbitmqctl add_vhost copy
sudo rabbitmqctl set_permissions -p "copy" "admin" ".*" ".*" ".*"
sudo rabbitmqctl set_permissions -p "copy" "userside" ".*" ".*" ".*"
sudo rabbitmqctl set_permissions -p "copy" "websock-user" "^erp-stomp:id-.*" "" "^erp-stomp:id-.*"
sudo rabbitmqctl --vhost copy set_user_tags "userside" "monitoring"

Now change the variable US_AMQP_DSN of the .env file this way:
US_AMQP_DSN=amqp://userside:yourpassword@127.0.0.1:5672/copy

* In version 3.16 and newer you will also need to recreate the venv for the poller microservice:
cd /var/www/userside-copy/microservice/poller
sudo rm -rf venv
sudo -H python3 -m venv venv
sudo -H venv/bin/pip install --upgrade -r requirements.txt

* Also starting with version 3.16 you will need to copy the supervisor configuration for the kernel background processes and the poller microservice. Also note that before version 3.18 the usm_poller.conf file was called us-poller-microservice.conf:
sudo cp /etc/supervisor/conf.d/us-core-worker.conf /etc/supervisor/conf.d/us-copy-core-worker.conf
sudo sed -i "s@us-core-worker@us-copy-core-worker@" "/etc/supervisor/conf.d/us-copy-core-worker.conf"
sudo sed -i "s@/var/www/userside/@/var/www/userside-copy/@" "/etc/supervisor/conf.d/us-copy-core-worker.conf"

sudo cp /etc/supervisor/conf.d/usm_poller.conf /etc/supervisor/conf.d/usm_poller_copy.conf
sudo sed -i "s@usm_poller@usm_poller_copy@" "/etc/supervisor/conf.d/usm_poller_copy.conf"
sudo sed -i "s@/var/www/userside/@/var/www/userside-copy/@" "/etc/supervisor/conf.d/usm_poller_copy.conf"

sudo systemctl restart supervisor

* it is now possible to open your copy in the browser.

HOWTO: Клонирование USERSIDE

2025-05-30T07:04:32Z

Uscld2:

[[HOWTO:_USERSIDE_cloning|en]] | [[HOWTO:_Клонирование_USERSIDE|ru]]

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

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

* скопируйте файлы приложения
cd /var/www/
sudo cp -r userside userside-copy

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

* скопируйте базу данных (или создайте новую базу данных и восстановите ее из резервной копии):
sudo -u postgres createdb -e --encoding="UTF-8" --locale="uk_UA.UTF-8" --owner=userside --template=userside userside_copy
если вы копируете базу данных на другой сервер, перед восстановлением вам нужно будет создать роль, обязательно такую же, как в дампе:
sudo -u postgres createuser userside -P

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

* Очистите базу данных Redis, которую собираетесь использовать:
redis-cli -n 1 -a пароль_redis FLUSHDB

* В версии до 3.13 отредактируйте параметры подключения к БД в файле common/config/db.php и URL в файле userside3/main/config/config.php

* В версии 3.16 и новее вам необходимо создать дополнительный vhost для RabbitMQ, а затем указать его в .env файле для переменной '''US_AMQP_DSN'''. В примере ниже в качестве имени нового vhost используется '''copy''' (измените на более удобное для вас, если в этом есть необходимость).Сперва выполните команду, создающую vhost, затем добавьте разрешения для пользователей в пределах этого vhost:
sudo rabbitmqctl add_vhost copy
sudo rabbitmqctl set_permissions -p "copy" "admin" ".*" ".*" ".*"
sudo rabbitmqctl set_permissions -p "copy" "userside" ".*" ".*" ".*"
sudo rabbitmqctl set_permissions -p "copy" "websock-user" "^erp-stomp:id-.*" "" "^erp-stomp:id-.*"
sudo rabbitmqctl --vhost copy set_user_tags "userside" "monitoring"

Теперь измените переменную US_AMQP_DSN файла .env таким образом:
US_AMQP_DSN=amqp://userside:вашпароль@127.0.0.1:5672/copy

* В версии 3.16 и новее вам также придется пересоздать venv для микросервиса поллера:
cd /var/www/userside-copy/microservice/poller
sudo rm -rf venv
sudo -H python3 -m venv venv
sudo -H venv/bin/pip install --upgrade -r requirements.txt

* Также начиная с версии 3.16 нужно будет скопировать конфигурацию супервизора для фоновых процессов ядра и микросервиса поллеров. Обратите внимание, что до версии 3.18 файл usm_poller.conf назывался us-poller-microservice.conf:
sudo cp /etc/supervisor/conf.d/us-core-worker.conf /etc/supervisor/conf.d/us-copy-core-worker.conf
sudo sed -i "s@us-core-worker@us-copy-core-worker@" "/etc/supervisor/conf.d/us-copy-core-worker.conf"
sudo sed -i "s@/var/www/userside/@/var/www/userside-copy/@" "/etc/supervisor/conf.d/us-copy-core-worker.conf"

sudo cp /etc/supervisor/conf.d/usm_poller.conf /etc/supervisor/conf.d/usm_poller_copy.conf
sudo sed -i "s@usm_poller@usm_poller_copy@" "/etc/supervisor/conf.d/usm_poller_copy.conf"
sudo sed -i "s@/var/www/userside/@/var/www/userside-copy/@" "/etc/supervisor/conf.d/usm_poller_copy.conf"

sudo systemctl restart supervisor

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

Upgrade 3.19

2025-05-29T14:46:10Z

Uscld2:

[[Upgrade_3.19|en]] | [[Обновление_3.19|ru]]

Version: '''[[3.19_EN|3.19]]'''

Version required: '''[[3.19_EN|3.10]] and above'''

== A few words from the author ==
* In version 3.19 we have done a lot to universalise and customise the system. Now every customer can switch off unused sections, create and operate completely arbitrary sections and entities, and change the naming of basic terms such as "Customers".

* Now we have "[[Two-Factor Authentication (2FA)]]". Don't neglect security and use it.

* Most files in the userside web directory have, for security reasons, changed their location several levels up and are now inaccessible via the web. Also changed the name of the directory that should be the root directory for the web to the default name public.

* System page/link routing has been changed
<pre>
It was: /?core_section=customer&action=show&id=1234
It became: /customer/1234
</pre>

* In version 3.19, the sections are declared obsolete:
** "Layout of construction lengths and assembled couplings for cable line routes". In version 3.20 the section will be removed
** "[[Unknown MAC-addresses]]". In version 3.20 the section will be removed
** "Technical support interface". In version 3.20 the section will be removed

* [[Upgrade]]. '''Recommended to have two instances of the system'''. A separate operational one and a separate test one. On the test one you can periodically update the database from the operational system and perform updates to make sure that everything is working, familiarise yourself with innovations or identify things that have stopped working for you.

* Our Telegram group for mutual communication of clients with each other: https://t.me/usersideeu and the news channel: https://t.me/userside

== Specifics in performing the upgrade ==

When upgrading in a Docker environment, refer to the [https://github.com/userside/userside-docker/tree/v3.18 instructions] in the Docker bundle repository.

* If you are upgrading from a version 3.10 - check out the page: [[Upgrade 3.11]]

* If you are upgrading from a version 3.11 and before - check out the page: [[Upgrade 3.12]]

* If you are upgrading from a version 3.12 and before - check out the page: [[Upgrade 3.13]]

* If you are upgrading from a version 3.13 and before - check out the page: [[Upgrade 3.14]]

* If you are upgrading from a version 3.14 and before - check out the page: [[Upgrade 3.15]]

* If you are upgrading from a version 3.15 and before - check out the page: [[Upgrade 3.16]]

* If you are upgrading from a version 3.16 and before - check out the page: [[Upgrade 3.17]]

* If you are upgrading from a version 3.17 and before - check out the page: [[Upgrade 3.18]]

* Move/remove extraneous files, directories, etc. from the userside directory (/var/www/userside). Only distribution files of the system itself and files that the system creates during its operation should be there. Userside modules (usm) should not be stored there either. Use separate directories for them (e.g. /opt/userside). Extraneous files in the userside directory can be removed during the upgrade process.

* Save the userside3/main/config/custom_api.php and userside3/main/skins/user_style.css ''(if any)'' files. These can come in handy in case of update errors and deleting them when doing so.

* Most files in the userside web directory have, for security reasons, changed their location several levels up and are now inaccessible via the web.

* Version 3.19 requires PHP version 8.3. You can install all the necessary packages in addition to your existing different PHP version. If you are using LDAP, also install php8.3-ldap. If you are using TurboSMS, install php8.3-soap.
sudo apt install -y php8.3-{fpm,cli,common,curl,intl,mbstring,opcache,pgsql,readline,xml,zip,snmp,gd}

* If php8.3 is not in your repository, use an alternative repository such as deb.sury.org by adding it to your system as follows and then repeating the PHP8.3 installation command above:
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

* Change the PHP configuration as follows and restart the php-fpm service.
<pre>
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@max_input_time.*@max_input_time = 300@" /etc/php/8.3/fpm/php.ini

sudo systemctl restart php8.3-fpm
</pre>

* create a new public directory inside the userside directory (if you have it installed elsewhere, edit the command before executing):
<pre>
sudo mkdir -p /var/www/userside/public
</pre>

* In the NGINX server configuration (/etc/nginx/conf.d/userside.conf), change the paths to the root directory. The line:
<pre>
root /var/www/userside/userside3;
</pre>
Replace it with:
<pre>
root /var/www/userside/public;
</pre>
* Also change there <code>location /</code> in its entirety for the next:
<pre>
location / {
try_files $uri $uri/ /index.php$is_args$args;
}
</pre>
* Also there for <code>location ~ \.php$</code> change the value for fastcgi_pass from:
fastcgi_pass unix:/run/php/php8.1-fpm.sock;
to
fastcgi_pass unix:/run/php/php8.3-fpm.sock;
and reread the nginx configuration:
sudo nginx -s reload

* For the websocket-user (websock-user) of the RabbitMQ broker, you need to change the permissions as follows:
<pre>
sudo rabbitmqctl set_permissions -p "/" "websock-user" "^erp-stomp:id-.*" "" "^erp-stomp:id-.*"
</pre>
If your websocket-user name is different from websock-user, specify it instead of websock-user in the above commands.

* Note that when you invoke the command <code>php</code> from the command line, php8.3 will now be invoked, since it is the latest version installed. If you're still using php8.1 anywhere, you'll need to change the php call in those places or change the alternate php command to run the version you want.

* USERSIDE 3.19 ''requires Python3 of any currently supported version. The status of versions can be viewed here:"[https://devguide.python.org/versions/ Status of Python versions]". It is recommended to use a version with "security" or "bugfix" status. Versions marked as "end-of-life" are not supported. Versions marked as "feature" are not recommended. If you have an unsupported version ("end-of-life") installed on your host, you should be sure to [[Python-update_EN|install additionally]] a more recent version of Python.''

* Use the automatic [[Installer|installer]] to perform [[Upgrade|upgrade]]:
sudo -u www-data php userside_install.phar install

* The following action only needs to be performed if you [[Python-update EN| updated Python]]. If you haven't updated, you don't need to do it:
<pre>
cd /var/www/userside/microservice/poller
sudo rm -rf venv
sudo python3.11 -m venv venv
</pre>

* You need to update (install) the dependencies for poller:
<pre>
cd /var/www/userside/microservice/poller
sudo venv/bin/pip install --upgrade pip
sudo venv/bin/pip install -U -r requirements.txt
</pre>

* And restart the services
<pre>
sudo supervisorctl restart all
</pre>

* Redesigned low-level interrogation of equipment ''(PON, TDR)''.

* The system of two SNMP-communities is replaced by one SNMP-community. This one SNMP-community will be the one that was specified in the rw-community field. If the rw-community field was empty - the value of the ro-community field will be used

* Don't forget to upgrade all modules to their latest versions

* If you are using the [[Usm_pon_EN|usm_pon]] module - reconfigure it to run at the required frequency in system cron, depending on how many OLTs you have. The module now polls only one device per run ''(previously all devices were polled simultaneously without the ability to mitigate load and skip unnecessary devices)''. Devices will be polled one at a time. At each startup, the next device with polling enabled will be polled.

* You can now configure separate notification templates for different types of tasks. Check your existing templates for correct migrations.

'''List of changes:''' [[3.19_EN|view]]

'''Performing an upgrade:''' [[Upgrade|instruction]]

Обновление 3.19

2025-05-29T14:45:25Z

Uscld2:

[[Upgrade_3.19|en]] | [[Обновление_3.19|ru]]

Версия: '''[[3.19]]'''

Требуется версия: '''[[3.10]] и выше'''

== Несколько слов от автора ==
* В версии 3.19 мы очень много сделали для универсализации и индивидуализации системы. Теперь каждый клиент может отключить неиспользуемые разделы, создать совершенно произвольные разделы и сущности и оперировать ими, а также изменять наименование базовых терминов - таких как "Абоненты"

* У нас появилась "[[Двухфакторная аутентификация (2FA)]]". Не пренебрегайте безопасностью и используйте её.

* Большинство файлов из веб-директории userside с целью безопасности изменили своё местоположение на несколько уровней выше и теперь недоступны через веб. Также изменилось имя каталога, который должен быть корневым для web, на стандартное имя public.

* Изменена маршрутизация страниц/ссылок системы
<pre>
Было: /?core_section=customer&action=show&id=1234
Стало: /customer/1234
</pre>

* В версии 3.19 объявляются устаревшими разделы:
** "Схема размещения строительных длин и смонтированных муфт для трасс кабельных линий". В версии 3.20 раздел будет удалён
** "[[Неизвестные MAC-адреса]]". В версии 3.20 раздел будет удалён
** "Интерфейс технической поддержки". В версии 3.20 раздел будет удалён

* [[Обновление]]. '''Рекомендую иметь два инстанса системы'''. Отдельно действующую и отдельно тестовую. На тестовой вы можете периодически обновлять базу данных с действующей системы и проводить обновление, убеждаясь, что всё работает, ознакомиться с нововведениями или выявлять моменты, которые у вас перестали работать.

* Наша группа в Telegram для взаимного общения клиентов между собой: https://t.me/usersideeu и канал для новостей: https://t.me/userside

== Особенности в проведении обновления ==

При обновлении в Docker-окружении, обратитесь к [https://github.com/userside/userside-docker/tree/v3.18 инструкциям] в репозитории Docker-бандла.

* Если вы обновляетесь с версии 3.10 - ознакомьтесь со страницей: [[Обновление 3.11]]

* Если вы обновляетесь с версии 3.11 и ранее - ознакомьтесь со страницей: [[Обновление 3.12]]

* Если вы обновляетесь с версии 3.12 и ранее - ознакомьтесь со страницей: [[Обновление 3.13]]

* Если вы обновляетесь с версии 3.13 и ранее - ознакомьтесь со страницей: [[Обновление 3.14]]

* Если вы обновляетесь с версии 3.14 и ранее - ознакомьтесь со страницей: [[Обновление 3.15]]

* Если вы обновляетесь с версии 3.15 и ранее - ознакомьтесь со страницей: [[Обновление 3.16]]

* Если вы обновляетесь с версии 3.16 и ранее - ознакомьтесь со страницей: [[Обновление 3.17]]

* Если вы обновляетесь с версии 3.17 и ранее - ознакомьтесь со страницей: [[Обновление 3.18]]

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

* Сохраните файлы ''(при их наличии)''
userside3/main/config/custom_api.php
userside3/main/skins/user_style.css
userside3/main/js/user_script.js

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

* Большинство файлов из веб-директории userside с целью безопасности изменили своё местоположение на несколько уровней выше и теперь недоступны через веб.

* Версия 3.19 требует PHP версии 8.3. Вы можете установить все необходимые пакеты дополнительно к уже существующей иной версии PHP. Если используете LDAP, то установите также php8.3-ldap. Если используете TurboSMS, то установите php8.3-soap.
sudo apt install -y php8.3-{fpm,cli,common,curl,intl,mbstring,opcache,pgsql,readline,xml,zip,snmp,gd}

* Если версия php8.3 отсутствует в вашем репозитории, то воспользуйтесь альтернативным репозиторием, например, deb.sury.org, добавив его в систему следующим образом и затем повторив команду установки PHP8.3 приведенную пунктом выше:
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

* Измените конфигурацию PHP следующим образом и перезапустите службу php-fpm.
<pre>
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@max_input_time.*@max_input_time = 300@" /etc/php/8.3/fpm/php.ini

sudo systemctl restart php8.3-fpm
</pre>

* создайте новый каталог public внутри каталога userside (если у вас установлено в другом месте, отредактируйте команду перед выполнением):
<pre>
sudo mkdir -p /var/www/userside/public
</pre>

* В настройке NGINX-сервера (/etc/nginx/conf.d/userside.conf) измените пути к корневому каталогу. Строку:
<pre>
root /var/www/userside/userside3;
</pre>
Замените на:
<pre>
root /var/www/userside/public;
</pre>
* Там же измените <code>location /</code> целиком на следующий:
<pre>
location / {
try_files $uri $uri/ /index.php$is_args$args;
}
</pre>
* Там же для <code>location ~ \.php$</code> измените значение для fastcgi_pass с:
fastcgi_pass unix:/run/php/php8.1-fpm.sock;
на
fastcgi_pass unix:/run/php/php8.3-fpm.sock;
и перечитайте конфигурацию nginx:
sudo nginx -s reload

* Для websocket-пользователя (websock-user) брокера RabbitMQ необходимо изменить разрешения следующим образом:
<pre>
sudo rabbitmqctl set_permissions -p "/" "websock-user" "^erp-stomp:id-.*" "" "^erp-stomp:id-.*"
</pre>
Если имя вашего websocket-пользователя отличается от websock-user, то укажите его вместо websock-user в приведенных выше командах.

* Обратите внимание, что при вызове команды <code>php</code> из командной строки, теперь будет вызываться php8.3, так как это последняя установленная версия. Если вы где-либо до сих пор используете php8.1, то вам нужно изменить вызов php в этих местах либо изменить альтернативную команду php, чтобы она запускала нужную вам версию.

* USERSIDE 3.19 ''требует Python3 любой поддерживаемой на данный момент версии. Статус версий можно посмотреть здесь: "[https://devguide.python.org/versions/ Status of Python versions]". Рекомендуется использовать версию с состоянием "security" или "bugfix". Версии отмеченные как "end-of-life" не поддерживаются. Отмеченные как "feature" не рекомендуется использовать. Если у вас на хосте неподдерживаемая версия ("end-of-life"), то нужно обязательно [[Python-update|установить дополнительно]] более свежую версию Python.''

* С помощью автоматического [[Инсталлятор|инсталлятора]] выполните [[Обновление|обновление]]:
sudo -u www-data php userside_install.phar install

* Следующее действие нужно выполнять только если вы [[Python-update|обновили Python]]. Если не обновляли, можно не выполнять:
<pre>
cd /var/www/userside/microservice/poller
sudo rm -rf venv
sudo python3.11 -m venv venv
</pre>

* Необходимо обновить (установить) зависимости для поллера:
<pre>
cd /var/www/userside/microservice/poller
sudo venv/bin/pip install --upgrade pip
sudo venv/bin/pip install -U -r requirements.txt
</pre>

* И перезапустить службы
<pre>
sudo supervisorctl restart all
</pre>

* Переработан низкоуровневый опрос оборудования ''(PON, TDR)''.

* Система двух SNMP-community заменена на один SNMP-community. Этим одним SNMP-community будет то, которое было указано в поле rw-community. Если поле rw-community было пустое - то будет использовано значение поля ro-community

* Не забудьте обновить все модули на их свежие версии

* Если вы используете модуль [[usm_pon]] - перенастройте в системном cron его запуск на нужную частоту в зависимости от количества у вас OLT. Теперь модуль опрашивает только одно устройство за запуск ''(ранее опрашивались все устройства одновременно без возможности смягчения нагрузки и пропуска ненужных устройств)''. Устройства будут опрашиваться по очереди. При каждом запуске на опрос будет подаваться следующее устройство у которого включен такой опрос.

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

'''Список изменений:''' [[3.19|просмотреть]]

'''Проведение обновления:''' [[Обновление|инструкция]]

Installation

2025-05-20T13:16:38Z

Uscld2: /* Main agreements */

<languages/>
[[Installation|en]] | [[Установка|ru]]

'''ATTENTION: These instructions are valid for ERP USERSIDE versions 3.19'''
* [[Installation for version 3.18|Instruction for version 3.18]]
* [[Installation for version 3.17|Instruction for version 3.11-3.17]]
* [[Installation for version 3.10 and earlier|Instruction for version 3.10 and earlier]].

== Description ==
For the sake of simplicity, the commands for the '''Linux Debian 12 (bookworm)''' operating system will be considered. For experienced system administrators, it should not be difficult to use similar commands for another operating system. If you do not feel confident in administering operating systems, we recommend you to use '''Debian''' or '''Ubuntu Server LTS'''. Because of their simplicity and because our technical support is much more familiar with Debian-like distributions. The likelihood of being able to tell you something not related to ERP USERSIDE, but related to operating system administration, will be much higher if you have Debian or a similar distribution based on it.

On the other hand, if you are an experienced system administrator and have skills and experience with Docker, it may be more convenient for you to use a ready-made environment based on Docker images that we have prepared specially, including everything you need to run ERP USERSIDE. In this case, you will not have to configure anything, except to perform simple Docker-bundle settings https://github.com/userside/userside-docker.

== Requirements ==
ERP USERSIDE requires various system applications and services such as PHP interpreter with a set of extensions, WEB server, database management system and others. This section will list such requirements depending on the version of ERP USERSIDE.

Also note that your operating system must be configured with the correct time zone and locale. The correct display of information and correct sorting depends on this.

The list of required PHP extensions contains all extensions that are not part of the PHP core. Some of these extensions may come with the core PHP package or as part of the php-common package, while others must be installed additionally.

=== 3.19 (current stable) ===
* PHP: 8.3
* PHP extensions: ctype, gd, json, libxml, mbstring, openssl, pdo, pdo_pgsql, posix, simplexml, snmp, sockets, zlib, pcntl
* Additional PHP extensions: ldap, soap
* Python: ''Requires Python3 of any currently supported version. The status of versions can be viewed here:"[https://devguide.python.org/versions/ Status of Python versions]". It is recommended to use a version with "security" or "bugfix" status. Versions marked as "end-of-life" are not supported. Versions marked as "feature" are not recommended.''
* Python modules: pip, venv
* PostgreSQL: 12+ (preferably 16)
* Redis: 5+ (preferably 7)
* RabbitMQ: 3.10+ (preferably 3.13)
* Supervisor

== Main agreements ==
The directory where ERP USERSIDE is installed is <code>/var/www/userside</code>. Inside this directory there should be a subdirectory public, which is the root directory for the WEB server. If you want to use a different directory for ERP USERSIDE, remember to make the appropriate corrections to all the examples in these instructions.

Create the directory:
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

You will need to allocate a domain name for ERP USERSIDE. The examples below use userside.mycompany.com, but you will need to change it to your own. Write this domain name in /etc/hosts if it is different from the hostname of the installation.

== Installation of the required components ==
First install the utilities that will be required later in the installation process. They are required for any ERP USERSIDE program. You can copy the lines one at a time and paste them into the command line of your operating system.

Copy and paste the following lines in their entirety:
<pre>
sudo tee /etc/apt/sources.list.d/contrib-non-free.list << EOL
deb http://deb.debian.org/debian/ $(lsb_release -sc) contrib non-free non-free-firmware
EOL

sudo apt update
sudo apt full-upgrade -y
sudo apt install -y gnupg ca-certificates lsb-release debian-archive-keyring debian-keyring libsnmp-dev snmp-mibs-downloader
</pre>

=== PostgreSQL ===
==== Alternative official repository ====
We strongly recommend using the latest version of PostgreSQL, as this always has a positive impact on speed. Add the official Postgres repository to the system:
<pre>
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
</pre>
If you have a different operating system, you can find the necessary commands for it at [https://www.postgresql.org/download/ official PostgreSQL website].

==== Installation ====
'''Attention!''' Before installing PostgreSQL, your operating system must have your local locale and correct time zone set! This can be done later, but it will be much easier if it is done before installing PostgreSQL. Run the following command to make sure the correct locale is present:
locale -a

If your local locale is not among those listed, then install it. To do this, simply edit the /etc/locale.gen file by removing the comments before the line(s) with the desired locale, and then run the command:
sudo locale-gen

If you need to change the default locale, run:
sudo dpkg-reconfigure locales

To change the time zone, execute:
sudo timedatectl set-timezone Europe/Kyiv

Now you can move on to the PostgreSQL installation:
sudo apt install -y postgresql-16 postgresql-16-postgis-3

==== Setting ====
Create a user and database for ERP USERSIDE. The example below creates a user named userside and a database with the same name. If your locale is not uk_UA, remember to change the command. The PostGis extension needed to work with geographic data is then connected to the database. After doing the first line, you will need to enter the password for the new user twice - make a note of this password, you will need it later to set up ERP USERSIDE
<pre>
sudo -u postgres createuser userside -P
sudo -u postgres createdb -e -E "UTF-8" -l "uk_UA.UTF-8" -O userside -T template0 userside
sudo -u postgres psql -d userside -c "CREATE EXTENSION postgis"
</pre>

If your PostgreSQL is installed '''on another server''', you will need to make corrections to the postgresql.conf and pg_hba.conf files located in the /etc/postgresql/16/main/ directory. In the postgresql.conf file, you must uncomment and change the value of the parameter <code>listen_addresses</code>, specifying there all IP addresses of the server interfaces on which it can accept connections to PostgreSQL. In the pg_hba.conf file you need to add a line at the very end, similar to the previous ones, indicating from which address the ERP USERSIDE user can connect. But if your PostgreSQL is located on the same server as USERSIDE - there is no need to make any adjustments to these files.

=== Redis ===
The Debian 12 standard repository includes Redis version 7.0.15. This version is suitable for running ERP USERSIDE.

==== Installation ====
sudo apt install -y redis-server

==== Setting ====
By default Redis accepts connections without a password, but we strongly recommend setting a password. Since the password is transmitted in the clear (Redis does not provide encryption because it focuses on speed of request processing and extra steps like encryption are not applied), you need to create a really long and complex password, for example, using the '''openssl''' utility as follows:

openssl rand --hex 32

The output will be a random set of 32 bytes in 16-character form, which you will use as a password. Next, you will need to substitute this generated string in place of the word '''MYPASSWORDHERE'''. Write it down. Then you will specify this string as the Redis password in the settings.

Specify the generated passphrase hash in the Redis configuration file:

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

where instead of '''MYPASSWORDHERE''' specify the hash of the passphrase received earlier.

You should also disable timeout (on some versions of Redis it is enabled):

sudo sed -i 's@^timeout .*@timeout 0@' /etc/redis/redis.conf

Restart Redis and make sure it works (should get PONG in response):
<pre>
sudo systemctl restart redis
redis-cli -h 127.0.0.1 -p 6379 -a MYPASSWORDHERE ping
</pre>

=== RabbitMQ ===
The Debian 12 standard repository includes an older version of RabbitMQ 3.10. You can use it - it is supported. However, this version is relatively old and your best bet is to install a newer version from alternative repositories. The [https://www.rabbitmq.com/install-debian.html official RabbitMQ website] has fairly detailed information on installing RabbitMQ for each operating system.

==== Adding alternative repositories ====
Copy and paste the following block in its entirety into the command line
<pre>
curl -1sLf https://dl.cloudsmith.io/public/rabbitmq/rabbitmq-erlang/gpg.E495BB49CC4BBE5B.key | sudo gpg --dearmor | sudo tee /usr/share/keyrings/rabbitmq-erlang-archive-keyring.gpg > /dev/null
curl -1sLf https://dl.cloudsmith.io/public/rabbitmq/rabbitmq-server/gpg.9F4587F226208342.key | sudo gpg --dearmor | sudo tee /usr/share/keyrings/rabbitmq-server-archive-keyring.gpg > /dev/null

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
</pre>

==== Installation ====
Make sure that /etc/hosts has an entry for your hostname. The lack of such an entry (for example, if you changed the hostname after installation) is a major error that occurs when installing RabbitMQ. So it is better to make sure again that there is an entry for the hostname.
<pre>
sudo apt install -y erlang-base \
erlang-asn1 erlang-crypto erlang-eldap erlang-ftp erlang-inets \
erlang-mnesia erlang-os-mon erlang-parsetools erlang-public-key \
erlang-runtime-tools erlang-snmp erlang-ssl \
erlang-syntax-tools erlang-tftp erlang-tools erlang-xmerl

sudo apt install rabbitmq-server -y --fix-missing
</pre>

==== Installation of necessary add-ons ====
Do the next two lines one at a time!
<pre>
sudo rabbitmq-plugins enable rabbitmq_management --offline

sudo rabbitmq-plugins enable rabbitmq_web_stomp --offline
</pre>

==== Setting ====
Copy and paste the following block in its entirety:
<pre>
sudo tee /etc/rabbitmq/rabbitmq.conf << EOF
listeners.tcp.default = 5672

web_stomp.port = 15674
web_stomp.cowboy_opts.max_keepalive = 60
EOF
</pre>

Now you need to create users. We recommend using '''three different users''': for server administration (full rights), for userside and modules (full rights but no administrative rights) and the web-stomp user for websocket (minimal rights to read certain broker objects). But you can only create two: an admin user, which will also be used for userside, and a user for websocket. These must necessarily be at least two different users, since the password for the websocket user is passed to the browser and can be easily read by the user. The following will show an example for the recommended three users.

Create a '''user for administration''' RabbitMQ. This example uses the username '''admin''' and password '''admin_password'''.
A tag <code>administrator</code> is assigned to the user immediately after creation, giving the user maximum administrator rights and then set permissions for vhost <code>/</code> allowing full access to configure, write and read everything within that vhost*.
<pre>
sudo rabbitmqctl add_user "admin" "admin_password"
sudo rabbitmqctl set_user_tags "admin" "administrator"
sudo rabbitmqctl set_permissions -p "/" "admin" ".*" ".*" ".*"
</pre>

Create a '''user on behalf of which ERP USERSIDE''' and modules will run. Example for the user name '''userside''' (you do not need to give admin rights to this user):
<pre>
sudo rabbitmqctl add_user "userside" "system_password"
sudo rabbitmqctl set_user_tags "userside" "monitoring"
sudo rabbitmqctl set_permissions -p "/" "userside" ".*" ".*" ".*"
</pre>

Create a '''WebSTOMP user''' . You will need it to use notifications via WebSocket. Instead of '''websock-user''' you can specify a different user name. Instead of '''password_websocket''' specify your password, but this password will be passed in the clear to the browser, so don't make it similar to other passwords:
<pre>
sudo rabbitmqctl add_user "websock-user" "password_websocket"
sudo rabbitmqctl set_permissions -p "/" "websock-user" "^erp-stomp:id-.*" "" "^erp-stomp:id-.*"
</pre>

Attention!: You will need to specify the WebSTOMP username and password in the settings in the USERSIDE interface (Menu: Settings - Main - Websocket).

''* vhost - is a virtual host within RabbitMQ that allows different applications to differentiate between different uses of the same server. Like, for example, different databases on the same DBMS server. The default vhost is named / and almost always this is enough for you. But if you plan, for example, to run multiple copies of ERP USERSIDE on the same server, then for each copy you will need to create a different vhost and, accordingly, users for it. Please refer to [https://www.rabbitmq.com/vhosts.html official manual] for more details.‘’

Restart the rabbitmq service:
<pre>
sudo systemctl restart rabbitmq-server
</pre>

==== Management ====
One of the commands above installs a management module in RabbitMQ that provides a convenient WEB interface to monitor, diagnose, and manage the RabbitMQ server. With this module you can monitor the server, keep track of the number of messages in queues and other statuses. All this can be done using the console utility as well <code>rabbitmqctl</code>, but using the WEB-interface can be much clearer and more convenient.

By default, the WEB management interface is available at http://userside.mycompany.com:15672. We recommend using a firewall to restrict access to this control interface.

More details about the control module can be [https://www.rabbitmq.com/management.html read on the official RabbitMQ website].

=== PHP ===
==== Alternative repository ====
<pre>
sudo curl -sSLo /usr/share/keyrings/deb.sury.org-php.gpg https://packages.sury.org/php/apt.gpg
sudo sh -c 'echo "deb [signed-by=/usr/share/keyrings/deb.sury.org-php.gpg] https://packages.sury.org/php/ $(lsb_release -sc) main" > /etc/apt/sources.list.d/php.list'
sudo apt update
</pre>

==== Installation ====
Execute the following commands:
<pre>
sudo apt install -y php8.3-{fpm,cli,common,curl,intl,mbstring,opcache,pgsql,readline,xml,zip,snmp,gd}
</pre>

If you plan to use LDAP, you need to install the php-ldap extension:
<pre>
sudo apt install -y php8.3-ldap
</pre>

If you plan to use TurboSMS to send SMS, you will also need the php-soap extension:
<pre>
sudo apt install -y php8.3-soap
</pre>

==== Setting ====
The following are commands that make changes to the configuration files.
<pre>
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
</pre>

=== NGINX ===
==== Alternative official repository ====
The version of NGINX supplied in the Debian repository is fully usable and there is no need to add an alternative repository. However, if you want to always have the latest version, run the following lines to add the official nginx repository to your operating system:
<pre>
curl https://nginx.org/keys/nginx_signing.key | gpg --dearmor \
| sudo tee /usr/share/keyrings/nginx-archive-keyring.gpg >/dev/null
echo "deb [signed-by=/usr/share/keyrings/nginx-archive-keyring.gpg] \
http://nginx.org/packages/debian `lsb_release -cs` nginx" \
| sudo tee /etc/apt/sources.list.d/nginx.list
echo -e "Package: *\nPin: origin nginx.org\nPin: release o=nginx\nPin-Priority: 900\n" \
| sudo tee /etc/apt/preferences.d/99nginx
sudo apt update
</pre>

If you have a different operating system, you can find the necessary commands for it on the official NGINX website: https://docs.nginx.com/nginx/admin-guide/installing-nginx/installing-nginx-open-source/

==== Installation ====
<pre>
sudo apt install -y nginx
</pre>

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

The following configuration example assumes that the ERP USERSIDE will be set to the system's default directory <code>/var/www/userside</code>. If you wish to install ERP USERSIDE in a different directory, please remember to fix it in all subsequent examples. In order not to make a mistake, we recommend to use exactly the directory <code>/var/www/userside</code>.

Now edit the file /etc/nginx/conf.d/default.conf. Or delete it and create a file named /etc/nginx/conf.d/userside.conf. In either case, regardless of your choice, the contents of the file should be as follows (instead of userside.mycompany.com, specify your domain name):
<pre>
server {
listen 80 default_server;
server_name userside.mycompany.com;
charset utf-8;
client_max_body_size 100M;

access_log /var/log/nginx/userside-access.log;
error_log /var/log/nginx/userside-error.log;

root /var/www/userside/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|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; }
}
</pre>

You may also want to configure SSL and something else. This topic is beyond the scope of this manual.

If you have installed RabbitMQ '''on another server''', or changed the value of the WebSTOMP port from 15674 to some other, then specify the IP address of the server with RabbitMQ and the port number in the line <code>proxy_pass http://127.0.0.1:15674/ws;</code>. The protocol must remain http. The path must remain /ws.

Check the configuration and if it is ok restart nginx:
sudo nginx -t && sudo nginx -s reload

=== Python ===
''Requires Python3 of any currently supported version. The status of versions can be viewed here:"[https://devguide.python.org/versions/ Status of Python versions]". It is recommended to use a version with "security" or "bugfix" status. Versions marked as "end-of-life" are not supported. Versions marked as "feature" are not recommended.''

If you have an unsupported version ("end-of-life") installed on your host, you should be sure to [[Python-update_EN|install additionally]] a more recent version of Python.

==== Installing the required packages ====
sudo apt install -y python3-dev python3-pip python3-venv libffi-dev pkg-config

=== Supervisor ===
sudo apt install -y supervisor

== Downloading and launching the installer ==

See also: [[Installer|Installer Help]]

1. navigate to the system catalogue
cd /var/www/userside

2. download the installer script
sudo -u www-data php -r "copy('https://my.userside.eu/install', 'userside_install.phar');"

3. run installer
sudo -u www-data php userside_install.phar install

During operation, the installer verifies compliance with technical requirements, requests access parameters, and checks connections to server services.

You can enter any ERP USERSIDE version number available to you for installation. To do this, you can enter the version number from the list (it contains only the latest version of each branch) or enter the entire version number if it is not on the list.

When the installer finishes, a message will be displayed indicating that the installation was successful.

If you did not install as a web server user, be sure to make that user the owner of all userside files recursively after the installation is complete!

sudo chown -R www-data:www-data /var/www/userside
sudo chmod -R u=rwX,g=rwX,o=r /var/www/userside

== Setting up after installation ==

=== Configuration of system services ===
After installation, copy the sample configuration files of the system services and, if necessary, customise them (for example, specify the path to the userside directory if it is different from /var/www/userside). Run the commands:
<pre>
sudo cp etc/us-core-worker.conf-example /etc/supervisor/conf.d/us-core-worker.conf
sudo cp microservice/poller/etc/usm_poller.conf-example /etc/supervisor/conf.d/usm_poller.conf
sudo cp etc/logrotate-example /etc/logrotate.d/userside
sudo cp microservice/poller/etc/logrotate-example /etc/logrotate.d/usm_poller
sudo cp etc/crontab-example /etc/cron.d/userside
</pre>

=== Installation of necessary dependencies for usm_poller ===
Create a venv virtual environment for python and install the dependent modules as shown below:
<pre>
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
</pre>

=== Running the supervisor ===
The Supervisor controls the operation of the services specified in its configuration. To launch the supervisor, run the following:
<pre>
sudo systemctl restart supervisor
</pre>
After the supervisor is launched, after a few seconds you can observe the state of all the services it controls. All services must be in the RUNNING state:
<pre>
sudo supervisorctl status
</pre>

== Immediately after the installation ==
This completes the installation of ERP USERSIDE. Now perform the following steps:
* Open the system page '''<nowiki>http://userside.mydomain.com/</nowiki>''' and login ''(default username: Admin, password: 1234)''.
* Configure Websocket under: Settings - Main - WebSocket. Enable and enter the username and password of the WebStomp user you created earlier under RabbitMQ.
* Make main settings in the section: [[Settings_-_Main|Settings - Main]].
* Configure interaction with [[Supported_billings|billing]] according to the [[Setting_up_interactions_with_a_billing|instructions]].
* Read the instructions on the page: [[Start_EN|Where to start?]].
* Configure the [[UserSide_API_Key|API Key]].

== System upgrade ==
We try to do our best to ensure that the likelihood of an end-to-end upgrade from any version to the latest version is successful. However, it sometimes happens that due to some ancient problems with the database structure that never prevented you from working before, a situation may arise in which an end-to-end upgrade is not possible. In this case you will have to upgrade step by step to each next latest version. For example, from 3.14.80 first to 3.15.60, then to 3.16.39, and so on.

Before upgrading, be sure to read about all the changes you need to make to upgrade for each version that lies between yours and the one you are going to upgrade to.

We recommend making a copy of your system to safely perform the upgrade. Refer to [[HOWTO: USERSIDE cloning]]. You can always delete the copy and start over. This is easy and safe. But if you wish to upgrade a running system, perform it at times of least stress, with time to spare for disaster recovery if something goes wrong. Always be sure to back up your database and files before upgrading. If an update is interrupted, especially during the data migration phase, there is a risk that it will be very difficult or even impossible to restore the data correctly. In general, the responsibility for having an up-to-date backup lies entirely with you.

==== Upgrade process ====
We strongly recommend performing test upgrades on a [[HOWTO: USERSIDE cloning|copy of the system]].

To perform an upgrade, run the installer in install mode and follow the instructions:
<pre>
cd /var/www/userside
sudo -u www-data php userside_install.phar install
</pre>

After upgrading the USERSIDE, you should be sure to upgrade the usm_poller dependencies:
<pre>
cd /var/www/userside/microservice/poller
sudo -H venv/bin/pip install -U pip
sudo -H venv/bin/pip install -U -r requirements.txt
</pre>

Now we need to restart all the services that are supervised by the supervisor and make sure that all of them start and are in the RUNNING state:
<pre>
sudo supervisorctl restart all
sudo supervisorctl status
</pre>

== System maintenance ==
To keep the system up to date and to ensure reliable operation in the future, it is recommended that you follow a few simple steps:
* periodically back up the database
* periodically create a backup copy of uploaded files (this can be done simply by archiving the /var/www/userside/var/attachments directory and the .env file)
* periodically monitor server performance (using htop, atop) and the RabbitMQ broker and make decisions about scaling fpm pools, kernel background processes and microservices

=== Backup ===
Set up periodic backups of the database and user files. Preferably at least once a day when the server is least loaded. In PostgreSQL, there are two ways to back up the database: dump and sql-script. Each of them has its own advantages and disadvantages. The first one creates a secure dump of the entire database, while the second one creates a SQL script that can restore both structure and data. We recommend referring to [https://www.postgresql.org/docs/current/app-pgdump.html documentation on how to use the pg_dump command] for a more suitable method or set of parameters for you.

Below are two commands for creating a database backup - choose one of them and add it to your crontab:
<pre>
# 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
</pre>

To create a minimal backup of '''files''' you can use the following command (for version 3.15 and later):
sudo tar -czf /backup/userside.tgz .env common/config/settings.json var/attachments
These files together with the database will be enough to restore USERSIDE. But you can back up the entire /var/www/userside directory for more reliability.

=== Restoring from a backup ===
The pg_restore command is used to restore from a dump. [https://postgrespro.ru/docs/postgresql/13/app-pgrestore Documentation on using pg_restore]. The psql utility is used to restore from a SQL script. [https://www.postgresql.org/docs/current/app-psql.html Documentation on using psql].

Before restoring the database from a backup, you must be sure to stop USERSIDE.

1. Stop cron userside and all modules
<pre>
mkdir -p ~/cron
sudo mv /etc/cron.d/userside ~/cron
sudo mv /etc/cron.d/userside-modules ~/cron
</pre>
2. Stop running background services
<pre>
sudo supervisorctl stop all
</pre>
3. Stop php-fpm from running
<pre>
sudo systemctl stop php8.3-fpm
</pre>
Only then can you proceed to restore the database from a backup copy.

==== SQL-script ====
To restore a database from a backup as a SQL script, you must first recreate the database and then restore to an empty backup database:
<pre>
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
</pre>

==== DUMP ====
The dump contains the entire database with all its elements. Therefore, before restoring a database from a dump, it must not exist on the server - delete the database before restoring from a dump. It is also important that the database user (the owner of all items) already exists - create it before restoring if you are restoring the database on a new server where the required user does not exist yet.

Also note that the dump structure may not be compatible between different versions of PostgreSQL. This is not necessarily the case, but it is likely.

To restore from the dump, use the commands:
<pre>
sudo -u postgres dropdb userside
sudo -u postgres pg_restore --clean --if-exists --create --exit-on-error --dbname=postgres userside.dump
</pre>
Note that the database name in the command must be '''postgres''', because the entire database is restored from the dump, not its contents.

==== After restoring the database ====
After restoring the database in any way, you must clear the ERP USERSIDE cache, as the cache now contains different data from the database. Go to the /var/www/userside directory and run the clear cache command (first, if a password is used, or second, if it is not used):
<pre>
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
</pre>
Restore services that were stopped before performing the backup:
<pre>
sudo mv ~/cron/* /etc/cron.d
sudo supervisorctl start all
sudo systemctl start php8.3-fpm
</pre>
Run the restore command to make the system files match the database version and check the system for file integrity.
<pre>
cd /var/www/userside
sudo -u www-data php userside_install.phar repair
</pre>

Установка

2025-05-20T13:16:27Z

Uscld2: /* Основные договорённости */

<languages/>
[[Installation|en]] | [[Установка|ru]]

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

== Описание ==
В целях упрощения будут рассмотрены команды для операционной системы '''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 любой поддерживаемой на данный момент версии. Статус версий можно посмотреть здесь: "[https://devguide.python.org/versions/ 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 - <code>/var/www/userside</code>. Внутри этого каталога должен быть подкаталог 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. Вы можете копировать строки по одной и вставлять их в командную строку вашей операционной системы.

Следующие строки скопируйте и вставьте целиком:
<pre>
sudo tee /etc/apt/sources.list.d/contrib-non-free.list << EOL
deb http://deb.debian.org/debian/ $(lsb_release -sc) contrib non-free non-free-firmware
EOL

sudo apt update
sudo apt full-upgrade -y
sudo apt install -y gnupg ca-certificates lsb-release debian-archive-keyring debian-keyring libsnmp-dev snmp-mibs-downloader
</pre>

=== PostgreSQL ===
==== Альтернативный официальный репозиторий ====
Мы настоятельно рекомендуем использовать последнюю версию PostgreSQL, так как это всегда положительно сказывается на скорости работы. Добавьте в систему официальный репозиторий Postgres:
<pre>
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
</pre>
Если у вас другая операционная система, вы можете найти необходимые команды для нее на [https://www.postgresql.org/download/ официальном сайте 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
<pre>
sudo -u postgres createuser userside -P
sudo -u postgres createdb -e -E "UTF-8" -l "uk_UA.UTF-8" -O userside -T template0 userside
sudo -u postgres psql -d userside -c "CREATE EXTENSION postgis"
</pre>

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

=== 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):
<pre>
sudo systemctl restart redis
redis-cli -h 127.0.0.1 -p 6379 -a MYPASSWORDHERE ping
</pre>

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

==== Добавление альтернативных репозиториев ====
Следующий блок скопируйте и вставьте целиком в командную строку
<pre>
curl -1sLf https://dl.cloudsmith.io/public/rabbitmq/rabbitmq-erlang/gpg.E495BB49CC4BBE5B.key | sudo gpg --dearmor | sudo tee /usr/share/keyrings/rabbitmq-erlang-archive-keyring.gpg > /dev/null
curl -1sLf https://dl.cloudsmith.io/public/rabbitmq/rabbitmq-server/gpg.9F4587F226208342.key | sudo gpg --dearmor | sudo tee /usr/share/keyrings/rabbitmq-server-archive-keyring.gpg > /dev/null

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
</pre>

==== Установка ====
Убедитесь, что в /etc/hosts есть запись для имени вашего хоста. Отсутствие такрой записи (например, если вы изменили имя хоста после инсталляции) является основной ошибкой, возникающей при установке RabbitMQ. Так что лучше еще раз убедитесь, что запись соответствующая имени хосту имеется.
<pre>
sudo apt install -y erlang-base \
erlang-asn1 erlang-crypto erlang-eldap erlang-ftp erlang-inets \
erlang-mnesia erlang-os-mon erlang-parsetools erlang-public-key \
erlang-runtime-tools erlang-snmp erlang-ssl \
erlang-syntax-tools erlang-tftp erlang-tools erlang-xmerl

sudo apt install rabbitmq-server -y --fix-missing
</pre>

==== Установка необходимых дополнений ====
Следующие две строки выполняйте по одной за раз!
<pre>
sudo rabbitmq-plugins enable rabbitmq_management --offline

sudo rabbitmq-plugins enable rabbitmq_web_stomp --offline
</pre>

==== Настройка ====
Скопируйте и вставьте целиком следующий блок:
<pre>
sudo tee /etc/rabbitmq/rabbitmq.conf << EOF
listeners.tcp.default = 5672

web_stomp.port = 15674
web_stomp.cowboy_opts.max_keepalive = 60
EOF
</pre>

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

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

Создайте '''пользователя, от имени которого будут работать ERP USERSIDE''' и модули. Пример для имени пользователя '''userside''' (наделять админскими правами этого пользователя не нужно):
<pre>
sudo rabbitmqctl add_user "userside" "пароль_системы"
sudo rabbitmqctl set_user_tags "userside" "monitoring"
sudo rabbitmqctl set_permissions -p "/" "userside" ".*" ".*" ".*"
</pre>

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

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

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

Перезапустите службу rabbitmq:
<pre>
sudo systemctl restart rabbitmq-server
</pre>

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

По умолчанию WEB-интерфейс управления доступен по адресу http://userside.mycompany.com:15672. Рекомендуем использовать фаервол, чтобы ограничить доступ к этому интерфейсу управления.

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

=== PHP ===
==== Альтернативный репозиторий ====
<pre>
sudo curl -sSLo /usr/share/keyrings/deb.sury.org-php.gpg https://packages.sury.org/php/apt.gpg
sudo sh -c 'echo "deb [signed-by=/usr/share/keyrings/deb.sury.org-php.gpg] https://packages.sury.org/php/ $(lsb_release -sc) main" > /etc/apt/sources.list.d/php.list'
sudo apt update
</pre>

==== Установка ====
Выполните следующие команды:
<pre>
sudo apt install -y php8.3-{fpm,cli,common,curl,intl,mbstring,opcache,pgsql,readline,xml,zip,snmp,gd}
</pre>

Если вы планируете использовать LDAP, необходимо установить расширение php-ldap:
<pre>
sudo apt install -y php8.3-ldap
</pre>

Если вы планируете использовать отправку SMS используя TurboSMS, также понадобится расширение php-soap:
<pre>
sudo apt install -y php8.3-soap
</pre>

==== Настройка ====
Далее приведены команды, вносящие изменения в файлы конфигурации.
<pre>
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
</pre>

=== NGINX ===
==== Альтернативный официальный репозиторий ====
Версия NGINX, поставляемая в репозитории Debian, полностью подходит для использования и нет необходимости в добавлении альтернативного репозитория. Однако, если вам хочется всегда иметь последнюю версию, то выполните следующие строки, чтобы добавить в операционную систему официальный репозиторий nginx:
<pre>
curl https://nginx.org/keys/nginx_signing.key | gpg --dearmor \
| sudo tee /usr/share/keyrings/nginx-archive-keyring.gpg >/dev/null
echo "deb [signed-by=/usr/share/keyrings/nginx-archive-keyring.gpg] \
http://nginx.org/packages/debian `lsb_release -cs` nginx" \
| sudo tee /etc/apt/sources.list.d/nginx.list
echo -e "Package: *\nPin: origin nginx.org\nPin: release o=nginx\nPin-Priority: 900\n" \
| sudo tee /etc/apt/preferences.d/99nginx
sudo apt update
</pre>

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

==== Установка ====
<pre>
sudo apt install -y nginx
</pre>

==== Настройка ====
<pre>
sudo sed -i "s@^user.*;@user www-data www-data;@" "/etc/nginx/nginx.conf"
sudo systemctl restart nginx
</pre>

Следующий пример настройки подразумевает, что ERP USERSIDE будет установлен в стандартный каталог системы <code>/var/www/userside</code>. Если вы желаете установить ERP USERSIDE в другой каталог, пожалуйста, не забывайте исправлять его во всех последующих примерах. Чтобы не ошибиться, мы рекомендуем использовать именно каталог <code>/var/www/userside</code>.

Теперь отредактируйте файл /etc/nginx/conf.d/default.conf. Либо удалите его и создайте файл с именем /etc/nginx/conf.d/userside.conf. В любом случае, не зависимо от вашего выбора, содержимое файла должно быть следующим (вместо userside.mycompany.com укажите свое доменное имя):
<pre>
server {
listen 80 default_server;
server_name userside.mycompany.com;
charset utf-8;
client_max_body_size 100M;

access_log /var/log/nginx/userside-access.log;
error_log /var/log/nginx/userside-error.log;

root /var/www/userside/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|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; }
}
</pre>

Также, возможно, вы захотите настроить SSL и что-либо еще. Эта тема выходит за рамки данной инстуркции.

Если Вы установили RabbitMQ '''на другом сервере''', либо изменили значение порта WebSTOMP с 15674 на какой-то другой, то укажите IP-адрес сервера с RabbitMQ и номер порта в строке <code>proxy_pass http://127.0.0.1:15674/ws;</code>. Протокол должен оставаться http. Путь должен оставаться /ws.

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

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

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

==== Установка необходимых пакетов ====
sudo apt install -y python3-dev python3-pip python3-venv libffi-dev pkg-config

=== Supervisor ===
sudo apt install -y supervisor

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

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

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

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

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

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

Вы можете ввести любой доступный вам номер версии 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). Выполните команды:
<pre>
sudo cp etc/us-core-worker.conf-example /etc/supervisor/conf.d/us-core-worker.conf
sudo cp microservice/poller/etc/usm_poller.conf-example /etc/supervisor/conf.d/usm_poller.conf
sudo cp etc/logrotate-example /etc/logrotate.d/userside
sudo cp microservice/poller/etc/logrotate-example /etc/logrotate.d/usm_poller
sudo cp etc/crontab-example /etc/cron.d/userside
</pre>

=== Установка необходимых зависимостей для usm_poller ===
Создайте виртуальное окружение venv для python и установите зависимые модули, как показано далее:
<pre>
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
</pre>

=== Запуск супервизора ===
Супервизор контролирует работу служб, указанных в его конфигурации. Для запуска супервизора выполните:
<pre>
sudo systemctl restart supervisor
</pre>
После запуска супервизора, спустя несколько секунд можно понаблюдать за состоянием всех контролируемых им служб. Все службы должны быть в состоянии RUNNING:
<pre>
sudo supervisorctl status
</pre>

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

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

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

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

==== Процесс обновления ====
Мы настоятельно рекомендуем выполнять тестовые обновления на [[HOWTO:_Клонирование_USERSIDE|копии системы]].

Для проведения обновления запустите инсталлятор в режиме install и следуйте инструкциям:
<pre>
cd /var/www/userside
sudo -u www-data php userside_install.phar install
</pre>

После обновления USERSIDE нужно обязательно обновить зависимости usm_poller:
<pre>
cd /var/www/userside/microservice/poller
sudo -H venv/bin/pip install -U pip
sudo -H venv/bin/pip install -U -r requirements.txt
</pre>

Теперь нужно перезапустить все службы, которолируемые супервизором и проследить чтобы все они запустились и были в состоянии RUNNING:
<pre>
sudo supervisorctl restart all
sudo supervisorctl status
</pre>

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

=== Резервное копирование ===
Установите периодическое резервное копирование базы данных и пользовательских файлов. Желательно минимум раз в сутки в моменты наименьшей нагрузки на сервер. В PostgreSQL существует два способа создать резервную копию базы данных: dump и sql-script. У каждого из них есть свои преимущества и недостатки. Первый создает безопасный дамп базы данных целиком, а второй создает SQL-скрипт, выполняя который можно восстановить как структуру так и данные. Рекомендуем обратиться к [https://www.postgresql.org/docs/current/app-pgdump.html документации по использованию команды pg_dump] для выбора более подходящего для вас способа или набора параметров.

Ниже приведены две команды для создания резервной копии базы данных — выбирайте одну из них и добавляйте в ваш crontab:
<pre>
# 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
</pre>

Для создания минимальной резервной копии '''файлов''' можно использовать следующую команду (для версии 3.15 и новее):
sudo tar -czf /backup/userside.tgz .env common/config/settings.json var/attachments
Этих файлов вместе с базой данных будет достаточно для восстановления работы USERSIDE. Но вы можете выполнять резервное копирование всего каталога /var/www/userside для большей надежности.

=== Восстановление из резервной копии ===
Для восстановления из дампа используется команда pg_restore. [https://postgrespro.ru/docs/postgresql/13/app-pgrestore Документация по использованию pg_restore]. Для восстановления из SQL-скрипта используется утилита psql. [https://www.postgresql.org/docs/current/app-psql.html Документация по использованию psql].

Перед восстановлением базы данных из резервной копии нужно обязательно остановить работу USERSIDE.

1. Остановить cron userside и всех модулей
<pre>
mkdir -p ~/cron
sudo mv /etc/cron.d/userside ~/cron
sudo mv /etc/cron.d/userside-modules ~/cron
</pre>
2. Остановить работу фоновых служб
<pre>
sudo supervisorctl stop all
</pre>
3. Остановить работу php-fpm
<pre>
sudo systemctl stop php8.3-fpm
</pre>
Только после этого можно приступать к восстановлению базы данных из резервной копии.

==== SQL-script ====
Для восстановления БД из резервной копии в виде SQL-скрипта, сначала нужно пересоздать базу данных, а затем восстановить в пустую базу данных резервную копию:
<pre>
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
</pre>

==== DUMP ====
Дамп содержит целиком базу данных со всеми ее элементами. Поэтому перед восстановлением базы данных из дампа её не должно существовать на сервере — удалите базу данных перед восстановлением из дампа. Также важно, чтобы пользователь базы данных (владелец всех элементов) уже существовал — создайте его перед восстановлением, если вы восстанавливаете базу данных на новом сервере, где нужного пользователя еще нет.

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

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

==== После восстановления базы данных ====
После восстановления базы данных любым способом, необходимо очистить кэш ERP USERSIDE, т.к. в кэше теперь находятся данные, отличные от данных в базе. Перейтите в каталог /var/www/userside и выполните команду очистки кэша (первую, если используется пароль или вторую, если не используется):
<pre>
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
</pre>
Восстановите работу служб, которые были остановлены перед выполнением резервной копии:
<pre>
sudo mv ~/cron/* /etc/cron.d
sudo supervisorctl start all
sudo systemctl start php8.3-fpm
</pre>
Выполните команду восстановления, чтобы файлы системы соответствовали версии базы данных и проверить систему на целостность файлов.
<pre>
cd /var/www/userside
sudo -u www-data php userside_install.phar repair
</pre>

FAQ. Error "ICMP Socket permission error: allow ICMP without root privileges."

2025-05-19T11:24:23Z

Uscld2:

FAQ. Ошибка "ICMP Socket permission error: allow ICMP without root privileges."

2025-05-19T11:24:13Z

Uscld2:

[[FAQ._Error_"ICMP_Socket_permission_error:_allow_ICMP_without_root_privileges."|en]] | [[FAQ._Ошибка_"ICMP_Socket_permission_error:_allow_ICMP_without_root_privileges."|ru]]

Ошибка с текстом <code>ICMP Socket permission error: allow ICMP without root privileges.</code> может возникать в usm_poller начиная с версии 3.19.18 и связана она с тем, что операционная система не разрешает использовать ICMP для непривилегированного пользователя. Начиная с версии 3.19.17 были внесены изменения в usm_poller, позволяющие запускать эту службу от имени простого пользователя, что положительно сказывается на безопасности. Если вы столкнулись с такой ошибкой, то вам нужно проделать следующее:

1. Остановите службу поллера:
<pre>sudo supervisorctl stop usm_poller:*</pre>
2. Измените значение параметра <code>user</code> в файле конфигурации службы /etc/supervisor/conf.d/usm_poller.conf на www-data (или любой другой на ваше усмотрение, но не root)
3. Удалите лог-файл (или измените его владельца на такого же, как в п.2) /var/log/usm_poller/poller.log
4. Перечитайте конфигурацию супервизора (это действие также перезапустит и службу), затем проверьте, что служба запустилась и все ее копии находятся в состоянии RUNNING:
<pre>sudo systemctl restart supervisor
sudo supervisorctl status</pre>
(возможно между командами придется выждать паузу в 10...15 секунд).

Теперь вернитесь в интерфейс ERP USERSIDE и проверьте, не пропала ли ошибка. Если ошибка все еще присутствует (это может быть на относительно старых операционных системах), то нужно изменить значение параметра <code>net.ipv4.ping_group_range</code> в sysctl.

Для этого выполните команды:
<pre>echo 'net.ipv4.ping_group_range = 0 2147483647' | sudo tee -a /etc/sysctl.conf
sudo sysctl -p</pre>

Если вы столкнулись с ошибкой invalid argument, то отредактируйте файл /etc/sysctl.conf и измените значение 2147483647 на 65535 и снова выполните:
<pre>sudo sysctl -p</pre>

Теперь вернитесь в интерфейс ERP USERSIDE и проверьте, не пропала ли ошибка. Если ошибка все еще присутствует, обратитесь в техподдержку.

Usm poller (as satellite) EN

2025-05-19T06:55:58Z

Uscld2:

[[Usm_poller_(as_satellite) EN|en]] | [[Usm_poller_(as_satellite)|ru]]

== Description ==

Since version 3.18 of USERSIDE, special '''usm_poller''' services are used to interact with telecommunications equipment, running in multiple copies on the operator's servers to increase availability, fault tolerance, and load balancing between servers. Special messages containing network jobs are passed between the USERSIDE kernel and these services, which are distributed to all usm_poller services via the RabbitMQ message broker, and in the same way report job results to the USERSIDE kernel via the service broker. The use of tools more suitable for network communication, as well as the asynchrony introduced into the system, allows the use of previously unavailable communication protocols, speeds up many communication scenarios over existing protocols, and does not make the user wait for the result in an open browser window.

Taking into account peculiarities of usm_poller services launching, it is possible to use these pollers instead of usm_satellite proxy modules, which were used in USERSIDE versions 3.13-3.17 for proxying commands of interaction with equipment between USERSIDE kernel and unavailable equipment via HTTP-API protocol. To do this, a simple setting was added to the usm_poller modules to identify a particular instance of usm_poller as a "satellite".

Since USERSIDE 3.18, the usm_poller module has been used as a "satellite" on remote nodes.

== Requirements ==
To run usm_poller on a remote communication node requires Docker (and optionally Compose plugin v2) or Python3 of any currently supported version and supervisor to run without Docker.

=== Versions ===
As the system is developed, there may be a situation where a new version of USERSIDE is not compatible with an older version of usm_poller. For example, when changes are made to the API or data structure or whatever.

All versions of USERSIDE from 3.18.0 up to and including 3.18.19 work with usm_poller versions 3.18.0 up to and including 3.18.7.

USERSIDE versions 3.18.20 and newer require a minimum usm_poller version of 3.18.8.

== Installing, configuring and running using Docker ==
Despite the fact that it is also possible to run without Docker, we strongly recommend using a Docker container to run Poller as a satellite. If for some reason you can't use Docker, below are instructions on how to run without Docker.

=== Installing Docker and Compose plugin ===
On most supported operating systems, running the command:
curl -fsSL get.docker.com | sh
This command will install the latest versions of Docker Engine and Compose Plugin on most supported operating systems. If this is not possible for your system, the command will provide recommendations for manual installation. You can also refer to the official [https://docs.docker.com/engine/install/ installation instructions] on the Docker project website. Note that the version of DockerIO that came with some Linux distributions is considered deprecated and is not suitable. At the same time, the Docker Desktop version designed for desktop operating systems is supported and you will be able to use it as well, but it is better to prefer Docker Engine (the server version of Docker).

If you need to run commands to Docker without using sudo, then add your user to the docker group with the following commands:
sudo gpasswd -a $USER docker
newgrp docker

Now verify that everything has installed correctly by running the commands:
docker version
docker compose version

=== Organisation of Poller-Broker communication ===
When using usm_satellite, the server was the module itself, while the client was the Userside kernel, which made HTTP-API requests to usm_satellite.

Now the server for all message consumers is the RabbitMQ broker, regardless of whether the application sends or receives a message. This means that the remote server on which usm_poller is installed as a satellite must have network access to the RabbitMQ broker installed on the Userside server (or on a separate server if that was necessary). At the same time, the remote server can now have no open ports at all, which increases its security.

[[Файл:Usm poller as satellite connection.png|900px|безрамки|центр]]

TCP port 5672 (AMQP protocol) is used by default to connect to the RabbitMQ broker. We recommend that you only access this port from the external network from IP addresses you know, which is the IP address of the remote satellite server on which you are running usm_poller.

If you are also using USERSIDE in the Docker bundle, then uncomment the line in the rabbitmq service ports responsible for broadcasting port 5672 (signed in the comments as AMQP) and restart the Docker bundle.

Alternatively, port 5672 (AMQP) can be port 5671 (AMQPS), which is not used by default. You can configure AMQPS (TLS) yourself in addition to port 5672 (AMQP). Instructions on how to configure TLS are available [https://rabbitmq.com/ssl.html in the official RabbitMQ documentation].

Since messages transmitted between the RabbitMQ broker and its consumers are transmitted in the plain form, the recommended option for organising communication is to use tunnelling with encryption between RabbitMQ nodes and a remote server with usm_poller.

=== Launching Docker containers usm_poller ===
The recommended way to start is to use the compose plugin. In this case, the entire configuration of the container is written in a special compose file, which makes it easier to use later.

You can create the compose file anywhere, but to avoid losing its location in the future, we recommend to put it, for example, in /opt/usm_poller. Create a directory:
sudo mkdir -p /opt/usm_poller

Then create a file named compose.yaml in this directory with the following contents (note the indents - they matter):

<pre>
services:
poller:
image: erpuserside/usm_poller:3.19
restart: unless-stopped
environment:
US_AMQP_DSN: amqp://user_name:password@host_address_rabbitmq:5672/%2f
USM_POLLER_SATELLITE_ID: your_satellite_id
deploy:
replicas: 1
</pre>

To work with USERSIDE 3.19.x, the erpuserside/usm_poller:3.19 image is used. The usm_poller version must be compatible with the specific version of USERSIDE (see above).

The value for <code>US_AMQP_DSN</code> is the URL string, which you can copy from the <code>.env</code> file located in the root directory with USERSIDE: /var/www/userside, but instead of the RabbitMQ IP address specified there, you need to specify the IP address where the RabbitMQ server is accessible (depends on which access method you use).

The value for <code>USM_POLLER_SATELLITE_ID</code> is the "satellite" identifier, which you can get from the page: Settings - Main - Equipment - Satellite Configuration.

Save the composer.yaml file and run it for a test as follows:
docker compose up

You should see the image being loaded, then the usm_poller Docker container being launched and connecting to the RabbitMQ server via AMQP. If the connection to the RabbitMQ server is correct, stop the container with Ctrl+C, change the number of replicas (replicas value) to 5 and start the containers in the background:
docker compose up -d

If five copies of the container will not be enough, increase this value. To determine if there are enough containers, open the RabbitMQ WEB console using the http protocol, the domain address of your userside and port 15672. For example, like this: http://userside.mycompany.com:15672 and then go to the Queues page. Find a queue there named <code>usm_poller-sat-7</code> (where 7 is the satellite ID), open it, and watch the queue fill up. The point is to ensure that pollers have time to pick up assignments within your normal time limit. Ideally, the queue should be almost empty at all times (tasks are immediately given to a free poller), or the number of messages should reach zero (the number of pollers is sufficient). You should not increase the number of replicas just for fun - this will lead to unnecessary overhead and may even end up negatively affecting performance if system resources are scarce.

After changing the number of replicas, you need to restart with the command:
docker compose restart

You can check the status of the containers with the command:
docker compose ps

To stop all containers, use the command:
docker compose stop

To upgrade the version of a Docker image within its version (this should preferably be done after each USERSIDE upgrade), you must first stop the containers, then edit the file to specify the new usm_poller version number and then start them in the background again:
docker compose down
nano compose.yaml
docker compose up -d

To avoid clogging the system with unused images, you can delete them by specifying the entire image with the version:
docker rmi erpuserside/usm_poller:3.19.2

If you think something isn't working properly, look at the container logs with the command:
docker compose logs poller

Or you can add the <code>-f</code> option to follow the logs in real time.

It is possible to start a single container without using compose, by executing just one command (consisting of several lines). However, although this method is simpler, it is not as convenient for later use:
docker run --detach \
--restart unless-stopped \
--name usm_poller \
--env US_AMQP_DSN=amqp://user_name:password@host_address_rabbitmq:5672/%2f \
--env USM_POLLER_SATELLITE_ID=your_satellite_id \
erpuserside/usm_poller:3.19

== Installation, configuration and running without Docker ==
The recommended way is to use Poller as a Docker container. In this case, all the necessary dependencies are inside the container and you don't need to take care of anything extra. Also the updates are done with a single command. But, if for some reason you can't use Docker, the only way is to run the poller directly on the host.

=== Creation of a copy of Poller for Satellite ===
First you need to copy the poller to the satellite server. To do this, you need to create an archive with the poller files on the USERSIDE server and then copy and unarchive them on the satellite server.

On the USERSIDE server, run:
<pre>
cd /var/www/userside/microserice
tar --exclude="venv" -czf usm_poller.tgz poller/
</pre>

Copy the usm_poller.tgz file to the satellite server. For example, to a directory <code>/opt</code> and run the following commands:
<pre>
tar xzf usm_poller.tgz
cd poller
</pre>

=== Installing dependencies ===
''Requires Python3 of any currently supported version. The status of versions can be viewed here:"[https://devguide.python.org/versions/ Status of Python versions]". It is recommended to use a version with "security" or "bugfix" status. Versions marked as "end-of-life" are not supported. Versions marked as "feature" are not recommended. If you have an unsupported version ("end-of-life") installed on your host, you should be sure to [[Python-update_EN|install additionally]] a more recent version of Python.''

Make sure the Python3 version is actual:
<pre>
python3 --version
</pre>

All following commands will be shown with the explicit version of Python. If you have a different version than the one shown in the commands - specify your version.

Install all necessary dependencies:
<pre>
sudo apt install -y supervisor libsnmp-dev
sudo -H python3 -m venv venv
sudo -H venv/bin/pip install -U pip wheel
sudo -H venv/bin/pip install -U -r requirements.txt
</pre>

=== Configuration and running ===
Create a <code>.env</code> file in which put the following variables:
<pre>
US_AMQP_DSN=amqp://username:password@address_host_rabbitmq:5672/%2f
USM_POLLER_SATELLITE_ID=id_your_satellite
USM_POLLER_LOGFILE=stdout
</pre>

Perform a test run:
<pre>
sudo -u www-data venv/bin/python worker.py
</pre>

You should see that the Poller has connected to the broker. Make sure that there are no errors. The running Poller is constantly running and waiting for messages from the broker. On the USERSIDE, do some polling of the equipment that is in the service area of this satellite and make sure that everything worked well. For example, you can open some switch and make sure that the information from the switch was taken by the poller and in the USERSIDE user interface you can see the result of this work.

Stop the poller running manually with the key combination Ctrl+C. You will have to wait about 5 seconds until the Poller completes all its tasks and closes the connection to the broker correctly.

From the <code>.env</code> file, delete the line with the <code>USM_POLLER_LOGFILE</code> variable. By default, logs are written to the file /var/log/usm_poller/poller.log. If you are not satisfied with this path, instead of deleting the variable, change its value to the file you need.

Copy the example supervisor settings and the example log rotation settings from the etc. subdirectory:
<pre>
sudo cp etc/usm_poller.conf-example /etc/supervisor/conf.d/usm_poller.conf
sudo cp etc/logrotate-example /etc/logrotate.d/usm_poller
</pre>

Edit the /etc/supervisor/conf.d/usm_poller.conf file. In it, change the path to the poller: instead of /var/www/userside/microservice/poller, specify /opt/poller or wherever you copied the poller to. Also specify the number of copies to run in the numprocs parameter. Depending on the amount of hardware and the number of tasks served by the satellite. Start with 2 and change this value as needed in the future. It makes no sense to run 15 copies at once. Besides, if your satellite server is not powerful enough, it may cause performance degradation.

Edit the /etc/logrotate.d/usm_poller file if you changed the path to the logs in the <code>.env</code> file environment variable <code>USM_POLLER_LOGFILE</code>.

Restart the supervisor to have it reread the configuration:
<pre>
sudo systemctl restart supervisor
</pre>

And after a few seconds, observe the processes it is controlling - all copies of the poller should be in the RUNNING state.
<pre>
sudo supervisorctl status
</pre>

The configuration is now complete.

=== Upgrade ===
To upgrade, you will have to make a Poller archive again from the USERSDIE server and move it to the satellite server, where you unarchive and install (upgrade) the dependencies again.

To do this, create an archive on the USERSIDE server:
<pre>
cd /var/www/userside/microserice
tar --exclude="venv" -czf usm_poller.tgz poller/
</pre>

Copy it to the satellite server in the /opt directory and unarchive it:
<pre>
tar xzf usm_poller.tgz
cd poller
</pre>

Upgrade dependencies:
<pre>
sudo -H venv/bin/pip install -U pip wheel
sudo -H venv/bin/pip install -U -r requirements.txt
</pre>

Restart the supervisor:
<pre>
sudo supervisorctl restart usm_poller:*
sudo supervisorctl status
</pre>

Usm poller (as satellite)

2025-05-19T06:54:00Z

Uscld2: /* Конфигурация и запуск */

[[Usm_poller_(as_satellite) EN|en]] | [[Usm_poller_(as_satellite)|ru]]

== Описание ==

Начиная с версии USERSIDE 3.18 для взаимодействия с телекоммуникационным оборудованием используются специальные службы '''usm_poller''', запускаемые в нескольких копиях на серверах оператора для увеличения доступности, отказоустойчивости и распределения нагрузки между серверами. Между ядром USERSIDE и этими службами передаются специальные сообщения, содержащие сетевые задания, которые через брокер сообщений RabbitMQ распределяются между всеми службами usm_poller и таким же образом через брокер службы сообщают ядру USERSIDE о результатах работы. Использование более подходящих для сетевого взаимодействия инструментов, а также внесенная в систему асинхронность позволяет использовать ранее недоступные протоколы связи, ускорить многие сценарии взаимодействия по существующим протоколам и не заставлять пользователя ждать результата в открытом окне браузера.

С учетом особенностей запуска служб usm_poller создается возможность использования этих поллеров вместо пркси-модулей usm_satellite, которые использовались в USERSIDE версиях 3.13-3.17 для проксирования команд взаимодействия с оборудованием между ядром USERSIDE и недоступным по сети оборудованием по протоколу HTTP-API. Для этого в модули usm_poller была добавлена простая настройка, идентифицирующая конкретный экземпляр usm_poller как "сателлит".

Начиная с версии USERSIDE 3.18 в качестве "сателлита" на удалённых узлах используется модуль usm_poller.

== Требования ==
Для запуска usm_poller на удалённом узле связи требуется наличие Docker (и опционально Compose plugin v2) или Python3 любой поддерживаемой на данный момент версии и supervisor для запуска без Docker.

=== Версии ===
По мере развития системы, может возникать ситуация, когда новая версия USERSIDE не совместима со старой версией usm_poller. Например, когда внесены изменения в API или структуру данных или что либо еще.

Все версии USERSIDE начиная с 3.18.0 и по 3.18.19 включительно работают с usm_poller версий 3.18.0 и по 3.18.7 включительно.

Версии USERSIDE 3.18.20 и более новые требуют минимальную версию usm_poller 3.18.8.

== Установка, настройка и запуск с использованием Docker ==
Несмотря на то, что также возможен запуск без Docker, мы настоятельно рекомендуем использовать Docker контейнер для запуска поллера в качестве сателлита. Если по каким-то причинам вы не можете использовать Docker, ниже дана инструкция по запуску без Docker.

=== Установка Docker и Compose plugin ===
В большинстве поддерживаемых операционных систем достаточно запуска команды:
curl -fsSL get.docker.com | sh
Эта команда установит Docker Engine и Compose Plugin последних версий на большинстве поддерживаемых операционных систем. Если для вашей системы это невозможно, команда выдаст рекомендации по ручной установке. Вы также можете обратиться к официальной [https://docs.docker.com/engine/install/ инструкции по установке] на сайте проекта Docker. Обратите внимание на то, что версия DockerIO, которая поставлялась с некоторыми дистрибутивами Linux, считается устаревшей и не подходит. Одновременно с этим, версия Docker Desktop, предназначенная для десктопных операционных систем, поддерживается и вы сможете также использовать и ее, но предпочтение лучше отдать Docker Engine (серверной версии Docker).

Если вам необходимо запускать команды к Docker без использования sudo, то добавьте своего пользователя в группу docker следующими командами:
sudo gpasswd -a $USER docker
newgrp docker

Теперь проверьте, что все установилось корректно, выполнив команды:
docker version
docker compose version

=== Организация связи поллера с брокером ===
При использовании usm_satellite сервером являлся сам модуль, в то время как клиентом являлось ядро Userside, которое выполняло HTTP-API запросы к usm_satellite.

Теперь сервером для всех потребителей сообщений является брокер RabbitMQ, не зависимо от того, отправляет приложение сообщение либо его принимает. Это означает, что удалённый сервер, на котором устанавливается usm_poller в качестве сателлита, должен иметь доступ по сети к брокеру RabbitMQ, установленному на сервере с Userside (либо на каком-то отдельном сервере, если в этом была необходимость). В то же время удаленный сервер теперь вообще может не иметь открытых портов, что повышает его безопасность.

[[Файл:Usm poller as satellite connection.png|900px|безрамки|центр]]

Для подключения к брокеру RabbitMQ по умолчанию используется TCP-порт 5672 (протокол AMQP). Мы рекомендуем открыть доступ к этому порту из внешней сети только с известных вам IP-адресов, коим является IP-адрес удаленного сервера-сателлита, на котором вы запускаете usm_poller.

Если вы используете и USERSIDE в Docker-бандле, то раскомментируйте строку в ports сервиса rabbitmq, отвечающую за трансляцию порта 5672 (подписан в комментариях как AMQP) и перезапустите Docker-бандл.

Также альтернативой порту 5672 (AMQP) может быть порт 5671 (AMQPS), который по умолчанию не используется. Вы можете настроить AMQPS (TLS) самостоятельно в дополнение к порту 5672 (AMQP). Инструкции по настройке TLS можно получить [https://rabbitmq.com/ssl.html в официальной документации RabbitMQ].

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

=== Запуск Docker-контейнеров usm_poller ===
Рекомендуемым способом запуска является использование плагина compose. В этом случая вся конфигурация контейнера прописывается в специальном compose-файле, что облегчает последующую эксплуатацию.

Вы можете создать compose-файл где угодно, но чтобы не потерять его расположение в будущем, рекомендуем расположить его, например, в /opt/usm_poller. Создайте каталог:
sudo mkdir -p /opt/usm_poller

Затем создайте файл с именем compose.yaml в этом каталоге и следующим содержимым (обратите внимание на отступы - они имеют значение):

<pre>
services:
poller:
image: erpuserside/usm_poller:3.19
restart: unless-stopped
environment:
US_AMQP_DSN: amqp://имя_пользователя:пароль@адрес_хоста_rabbitmq:5672/%2f
USM_POLLER_SATELLITE_ID: id_вашего_satellite
deploy:
replicas: 1
</pre>

Для работы с USERSIDE 3.19.x используется образ erpuserside/usm_poller:3.19. Версия usm_poller должна быть совместима с конкретной версией USERSIDE (см. выше).

Значением для <code>US_AMQP_DSN</code> является URL-строка, которую вы можете скопировать из файла <code>.env</code>, расположенного в корневом каталоге с USERSIDE: /var/www/userside, но вместо IP-адреса RabbitMQ, указанного там, вам нужно указать тот IP-адрес, по которому доступен сервер RabbitMQ (зависит от того, какой способ доступа вы используете).

Значением для <code>USM_POLLER_SATELLITE_ID</code> является идентификатор "сателлита", который вы можете взять со страницы: Настройка - Основная - Оборудование - Настройка сателлитов.

Сохраните файл composer.yaml и запустите для теста следующим образом:
docker compose up

Вы должны увидеть, как загружается образ, затем происходит запуск Docker-контейнера usm_poller и подключение к серверу RabbitMQ по протоколу AMQP. Если подключение к RabbitMQ серверу произошло корректно, то остановите работу контейнера сочетанием Ctrl+C, измените количество реплик (значение replicas) до 5 и запустите контейнеры в фоновом режиме:
docker compose up -d

Если пяти копий контейнера будет мало, увеличьте это значение. Чтобы определить, достаточно ли контейнеров, откройте WEB-консоль RabbitMQ используя протокол http, адрес домена вашего userside и порт 15672. Например, вот так: http://userside.mycompany.com:15672 и затем перейдите на страницу Queues. Найдите там очередь с именем <code>usm_poller-sat-7</code> (где 7 — это идентификатор сателлита), откройте ее и понаблюдайте за заполнением очереди. Смысл заключается в том, чтобы поллеры успевали забирать задания в пределах нормального для вас времени. В идеале, очередь должна быть практически пустой всегда (задания сразу же отдаются свободному поллеру), либо количество сообщений должно доходить до нуля (количество поллеров достаточно). Не стоит увеличивать количество реплик просто так — это приведет к ненужному накладному расходу ресурсов и в итоге может даже отрицательно сказаться на производительности, если ресурсов системы будет не хватать.

После изменения количества реплик, нужно выполнить перезапуск командой:
docker compose restart

Посмотреть состояние контейнеров можно командой:
docker compose ps

Чтобы остановить все контейнеры, используйте команду:
docker compose stop

Чтобы обновить версию Docker-образа в пределах его версии (это желательно делать после каждого обновления USERSIDE), нужно сначала остановить контейнеры, затем отредактировать файл, указав номер новой версии usm_poller и затем снова запустить их в фоне:
docker compose down
nano compose.yaml
docker compose up -d

Чтобы не засорять систему не используемыми образами, их можно удалять, указывая образ целиком с версией:
docker rmi erpuserside/usm_poller:3.19.2

Если вам кажется, что что-то работает не так как нужно, посмотрите логи контейнеров командой:
docker compose logs poller

Либо же можно добавить опцию <code>-f</code> чтобы наблюдать follow за логами в реальном времени.

Запустить один контейнер можно и без использования compose, выполнив всего лишь одну команду (состоящую из нескольких строк). Однако такой способ хоть и является более простым, все же не так удобен для последующей эксплуатации:
docker run --detach \
--restart unless-stopped \
--name usm_poller \
--env US_AMQP_DSN=amqp://имя_пользователя:пароль@адрес_хоста_rabbitmq:5672/%2f \
--env USM_POLLER_SATELLITE_ID=id_вашего_satellite \
erpuserside/usm_poller:3.19

== Установка, настройка и запуск без Docker ==
Рекомендуемым способом является использование поллера в качестве Docker контейнера. В этом случае все необходимые зависимости находятся внутри контейнера и вам не нужно дополнительно ни о чем заботиться. Также и обновления выполняются одной командой. Но, если по какой-то причине вы не можете использовать Docker, то единственным способом является запуск поллера прямо на хосте.

=== Создание копии поллера для сателлита ===
Для начала вам нужно скопировать поллер на сателлит-сервер. Для этого вам нужно создать архив с файлами поллера на сервере с USERSIDE и затем скопировать и разархивировать их на сателлит-сервере.

На сервере USERSIDE выполните:
<pre>
cd /var/www/userside/microserice
tar --exclude="venv" -czf usm_poller.tgz poller/
</pre>

Скопируйте файл usm_poller.tgz на сателлит-сервер. Например, в каталог <code>/opt</code> и выполните следующие команды:
<pre>
tar xzf usm_poller.tgz
cd poller
</pre>

=== Установка зависимостей ===

''Необходим Python3 любой поддерживаемой на данный момент версии. Статус версий можно посмотреть здесь: "[https://devguide.python.org/versions/ Status of Python versions]". Рекомендуется использовать версию с состоянием "security" или "bugfix". Версии отмеченные как "end-of-life" не поддерживаются. Отмеченные как "feature" не рекомендуется использовать. Если у вас на хосте неподдерживаемая версия ("end-of-life"), то нужно обязательно [[Python-update|установить дополнительно]] более свежую версию Python.''

Убедитесь, что версия Python3 актуальна:
<pre>
python3 --version
</pre>

Все последующие команды будут показаны с указанием явной версии Python. Если у вас версия отличается от указанной в командах - указывайте вашу версию.

Установите все необходимые зависимости:
<pre>
sudo apt install -y supervisor libsnmp-dev
sudo -H python3 -m venv venv
sudo -H venv/bin/pip install -U pip wheel
sudo -H venv/bin/pip install -U -r requirements.txt
</pre>

=== Конфигурация и запуск ===
Создайте файл <code>.env</code> в который поместите следующие переменые:
<pre>
US_AMQP_DSN=amqp://имя_пользователя:пароль@адрес_хоста_rabbitmq:5672/%2f
USM_POLLER_SATELLITE_ID=id_вашего_satellite
USM_POLLER_LOGFILE=stdout
</pre>

Выполните тестовый запуск:
<pre>
sudo -u www-data venv/bin/python worker.py
</pre>

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

Остановите работу поллера, запущенного вручную, комбинацией клавиш Ctrl+C. Придется подождать около 5 сек, пока поллер завершит все свои задачи и корректно закроет подключение к брокеру.

Из файла <code>.env</code> удалите строку с переменной <code>USM_POLLER_LOGFILE</code>. По умолчанию логи пишутся в файл /var/log/usm_poller/poller.log. Если вас не устраивает этот путь, то вместо удаления переменной, измените ее значение на нужный вам файл.

Скопируйте пример настроек супервизора и пример настроек ротации логов из подкаталога etc:
<pre>
sudo cp etc/usm_poller.conf-example /etc/supervisor/conf.d/usm_poller.conf
sudo cp etc/logrotate-example /etc/logrotate.d/usm_poller
</pre>

Отредактируйте файл /etc/supervisor/conf.d/usm_poller.conf. В нем измените путь к поллеру: вместо /var/www/userside/microservice/poller укажите /opt/poller или тот, куда вы скопировали поллер. Также укажите количество запускаемых копий в параметре numprocs. В зависимости от количества оборудования и количества задач, обслуживаемых сателлитом. Начните с 2 и по мере необходимости в будущем изменяйте это значение. Запускать сразу 15 копий нет смысла. К тому же, если ваш сателлит-сервер недостаточно мощный, то это может привести к деградации производительности.

Отредактируйте файл /etc/logrotate.d/usm_poller если вы изменили путь к логам в переменной окружения <code>USM_POLLER_LOGFILE</code> файла <code>.env</code>.

Перезапустите супервизор, чтобы он перечитал конфигурацию:
<pre>
sudo systemctl restart supervisor
</pre>

И спустя несколько секунд понаблюдайте за процессами, которые он контролирует - все копии поллера должны быть в состоянии RUNNING.
<pre>
sudo supervisorctl status
</pre>

На этом настройка закончена.

=== Обновление ===
Для обновления вам придется снова делать архив поллера с сервера USERSDIE и переносить его на сателлит-сервер, где разархивировать и снова устанавливать (обновлять) зависимости.

Для этого на сервере USERSIDE создайте архив:
<pre>
cd /var/www/userside/microserice
tar --exclude="venv" -czf usm_poller.tgz poller/
</pre>

Скопируйте его на сателлит сервер в каталог /opt и разархивируйте:
<pre>
tar xzf usm_poller.tgz
cd poller
</pre>

Обновите зависимости:
<pre>
sudo -H venv/bin/pip install -U pip wheel
sudo -H venv/bin/pip install -U -r requirements.txt
</pre>

Перезапустите супервизор:
<pre>
sudo supervisorctl restart usm_poller:*
sudo supervisorctl status
</pre>

Usm poller (as satellite)

2025-05-19T06:52:52Z

Uscld2: /* Запуск Docker-контейнеров usm_poller */

[[Usm_poller_(as_satellite) EN|en]] | [[Usm_poller_(as_satellite)|ru]]

== Описание ==

Начиная с версии USERSIDE 3.18 для взаимодействия с телекоммуникационным оборудованием используются специальные службы '''usm_poller''', запускаемые в нескольких копиях на серверах оператора для увеличения доступности, отказоустойчивости и распределения нагрузки между серверами. Между ядром USERSIDE и этими службами передаются специальные сообщения, содержащие сетевые задания, которые через брокер сообщений RabbitMQ распределяются между всеми службами usm_poller и таким же образом через брокер службы сообщают ядру USERSIDE о результатах работы. Использование более подходящих для сетевого взаимодействия инструментов, а также внесенная в систему асинхронность позволяет использовать ранее недоступные протоколы связи, ускорить многие сценарии взаимодействия по существующим протоколам и не заставлять пользователя ждать результата в открытом окне браузера.

С учетом особенностей запуска служб usm_poller создается возможность использования этих поллеров вместо пркси-модулей usm_satellite, которые использовались в USERSIDE версиях 3.13-3.17 для проксирования команд взаимодействия с оборудованием между ядром USERSIDE и недоступным по сети оборудованием по протоколу HTTP-API. Для этого в модули usm_poller была добавлена простая настройка, идентифицирующая конкретный экземпляр usm_poller как "сателлит".

Начиная с версии USERSIDE 3.18 в качестве "сателлита" на удалённых узлах используется модуль usm_poller.

== Требования ==
Для запуска usm_poller на удалённом узле связи требуется наличие Docker (и опционально Compose plugin v2) или Python3 любой поддерживаемой на данный момент версии и supervisor для запуска без Docker.

=== Версии ===
По мере развития системы, может возникать ситуация, когда новая версия USERSIDE не совместима со старой версией usm_poller. Например, когда внесены изменения в API или структуру данных или что либо еще.

Все версии USERSIDE начиная с 3.18.0 и по 3.18.19 включительно работают с usm_poller версий 3.18.0 и по 3.18.7 включительно.

Версии USERSIDE 3.18.20 и более новые требуют минимальную версию usm_poller 3.18.8.

== Установка, настройка и запуск с использованием Docker ==
Несмотря на то, что также возможен запуск без Docker, мы настоятельно рекомендуем использовать Docker контейнер для запуска поллера в качестве сателлита. Если по каким-то причинам вы не можете использовать Docker, ниже дана инструкция по запуску без Docker.

=== Установка Docker и Compose plugin ===
В большинстве поддерживаемых операционных систем достаточно запуска команды:
curl -fsSL get.docker.com | sh
Эта команда установит Docker Engine и Compose Plugin последних версий на большинстве поддерживаемых операционных систем. Если для вашей системы это невозможно, команда выдаст рекомендации по ручной установке. Вы также можете обратиться к официальной [https://docs.docker.com/engine/install/ инструкции по установке] на сайте проекта Docker. Обратите внимание на то, что версия DockerIO, которая поставлялась с некоторыми дистрибутивами Linux, считается устаревшей и не подходит. Одновременно с этим, версия Docker Desktop, предназначенная для десктопных операционных систем, поддерживается и вы сможете также использовать и ее, но предпочтение лучше отдать Docker Engine (серверной версии Docker).

Если вам необходимо запускать команды к Docker без использования sudo, то добавьте своего пользователя в группу docker следующими командами:
sudo gpasswd -a $USER docker
newgrp docker

Теперь проверьте, что все установилось корректно, выполнив команды:
docker version
docker compose version

=== Организация связи поллера с брокером ===
При использовании usm_satellite сервером являлся сам модуль, в то время как клиентом являлось ядро Userside, которое выполняло HTTP-API запросы к usm_satellite.

Теперь сервером для всех потребителей сообщений является брокер RabbitMQ, не зависимо от того, отправляет приложение сообщение либо его принимает. Это означает, что удалённый сервер, на котором устанавливается usm_poller в качестве сателлита, должен иметь доступ по сети к брокеру RabbitMQ, установленному на сервере с Userside (либо на каком-то отдельном сервере, если в этом была необходимость). В то же время удаленный сервер теперь вообще может не иметь открытых портов, что повышает его безопасность.

[[Файл:Usm poller as satellite connection.png|900px|безрамки|центр]]

Для подключения к брокеру RabbitMQ по умолчанию используется TCP-порт 5672 (протокол AMQP). Мы рекомендуем открыть доступ к этому порту из внешней сети только с известных вам IP-адресов, коим является IP-адрес удаленного сервера-сателлита, на котором вы запускаете usm_poller.

Если вы используете и USERSIDE в Docker-бандле, то раскомментируйте строку в ports сервиса rabbitmq, отвечающую за трансляцию порта 5672 (подписан в комментариях как AMQP) и перезапустите Docker-бандл.

Также альтернативой порту 5672 (AMQP) может быть порт 5671 (AMQPS), который по умолчанию не используется. Вы можете настроить AMQPS (TLS) самостоятельно в дополнение к порту 5672 (AMQP). Инструкции по настройке TLS можно получить [https://rabbitmq.com/ssl.html в официальной документации RabbitMQ].

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

=== Запуск Docker-контейнеров usm_poller ===
Рекомендуемым способом запуска является использование плагина compose. В этом случая вся конфигурация контейнера прописывается в специальном compose-файле, что облегчает последующую эксплуатацию.

Вы можете создать compose-файл где угодно, но чтобы не потерять его расположение в будущем, рекомендуем расположить его, например, в /opt/usm_poller. Создайте каталог:
sudo mkdir -p /opt/usm_poller

Затем создайте файл с именем compose.yaml в этом каталоге и следующим содержимым (обратите внимание на отступы - они имеют значение):

<pre>
services:
poller:
image: erpuserside/usm_poller:3.19
restart: unless-stopped
environment:
US_AMQP_DSN: amqp://имя_пользователя:пароль@адрес_хоста_rabbitmq:5672/%2f
USM_POLLER_SATELLITE_ID: id_вашего_satellite
deploy:
replicas: 1
</pre>

Для работы с USERSIDE 3.19.x используется образ erpuserside/usm_poller:3.19. Версия usm_poller должна быть совместима с конкретной версией USERSIDE (см. выше).

Значением для <code>US_AMQP_DSN</code> является URL-строка, которую вы можете скопировать из файла <code>.env</code>, расположенного в корневом каталоге с USERSIDE: /var/www/userside, но вместо IP-адреса RabbitMQ, указанного там, вам нужно указать тот IP-адрес, по которому доступен сервер RabbitMQ (зависит от того, какой способ доступа вы используете).

Значением для <code>USM_POLLER_SATELLITE_ID</code> является идентификатор "сателлита", который вы можете взять со страницы: Настройка - Основная - Оборудование - Настройка сателлитов.

Сохраните файл composer.yaml и запустите для теста следующим образом:
docker compose up

Вы должны увидеть, как загружается образ, затем происходит запуск Docker-контейнера usm_poller и подключение к серверу RabbitMQ по протоколу AMQP. Если подключение к RabbitMQ серверу произошло корректно, то остановите работу контейнера сочетанием Ctrl+C, измените количество реплик (значение replicas) до 5 и запустите контейнеры в фоновом режиме:
docker compose up -d

Если пяти копий контейнера будет мало, увеличьте это значение. Чтобы определить, достаточно ли контейнеров, откройте WEB-консоль RabbitMQ используя протокол http, адрес домена вашего userside и порт 15672. Например, вот так: http://userside.mycompany.com:15672 и затем перейдите на страницу Queues. Найдите там очередь с именем <code>usm_poller-sat-7</code> (где 7 — это идентификатор сателлита), откройте ее и понаблюдайте за заполнением очереди. Смысл заключается в том, чтобы поллеры успевали забирать задания в пределах нормального для вас времени. В идеале, очередь должна быть практически пустой всегда (задания сразу же отдаются свободному поллеру), либо количество сообщений должно доходить до нуля (количество поллеров достаточно). Не стоит увеличивать количество реплик просто так — это приведет к ненужному накладному расходу ресурсов и в итоге может даже отрицательно сказаться на производительности, если ресурсов системы будет не хватать.

После изменения количества реплик, нужно выполнить перезапуск командой:
docker compose restart

Посмотреть состояние контейнеров можно командой:
docker compose ps

Чтобы остановить все контейнеры, используйте команду:
docker compose stop

Чтобы обновить версию Docker-образа в пределах его версии (это желательно делать после каждого обновления USERSIDE), нужно сначала остановить контейнеры, затем отредактировать файл, указав номер новой версии usm_poller и затем снова запустить их в фоне:
docker compose down
nano compose.yaml
docker compose up -d

Чтобы не засорять систему не используемыми образами, их можно удалять, указывая образ целиком с версией:
docker rmi erpuserside/usm_poller:3.19.2

Если вам кажется, что что-то работает не так как нужно, посмотрите логи контейнеров командой:
docker compose logs poller

Либо же можно добавить опцию <code>-f</code> чтобы наблюдать follow за логами в реальном времени.

Запустить один контейнер можно и без использования compose, выполнив всего лишь одну команду (состоящую из нескольких строк). Однако такой способ хоть и является более простым, все же не так удобен для последующей эксплуатации:
docker run --detach \
--restart unless-stopped \
--name usm_poller \
--env US_AMQP_DSN=amqp://имя_пользователя:пароль@адрес_хоста_rabbitmq:5672/%2f \
--env USM_POLLER_SATELLITE_ID=id_вашего_satellite \
erpuserside/usm_poller:3.19

== Установка, настройка и запуск без Docker ==
Рекомендуемым способом является использование поллера в качестве Docker контейнера. В этом случае все необходимые зависимости находятся внутри контейнера и вам не нужно дополнительно ни о чем заботиться. Также и обновления выполняются одной командой. Но, если по какой-то причине вы не можете использовать Docker, то единственным способом является запуск поллера прямо на хосте.

=== Создание копии поллера для сателлита ===
Для начала вам нужно скопировать поллер на сателлит-сервер. Для этого вам нужно создать архив с файлами поллера на сервере с USERSIDE и затем скопировать и разархивировать их на сателлит-сервере.

На сервере USERSIDE выполните:
<pre>
cd /var/www/userside/microserice
tar --exclude="venv" -czf usm_poller.tgz poller/
</pre>

Скопируйте файл usm_poller.tgz на сателлит-сервер. Например, в каталог <code>/opt</code> и выполните следующие команды:
<pre>
tar xzf usm_poller.tgz
cd poller
</pre>

=== Установка зависимостей ===

''Необходим Python3 любой поддерживаемой на данный момент версии. Статус версий можно посмотреть здесь: "[https://devguide.python.org/versions/ Status of Python versions]". Рекомендуется использовать версию с состоянием "security" или "bugfix". Версии отмеченные как "end-of-life" не поддерживаются. Отмеченные как "feature" не рекомендуется использовать. Если у вас на хосте неподдерживаемая версия ("end-of-life"), то нужно обязательно [[Python-update|установить дополнительно]] более свежую версию Python.''

Убедитесь, что версия Python3 актуальна:
<pre>
python3 --version
</pre>

Все последующие команды будут показаны с указанием явной версии Python. Если у вас версия отличается от указанной в командах - указывайте вашу версию.

Установите все необходимые зависимости:
<pre>
sudo apt install -y supervisor libsnmp-dev
sudo -H python3 -m venv venv
sudo -H venv/bin/pip install -U pip wheel
sudo -H venv/bin/pip install -U -r requirements.txt
</pre>

=== Конфигурация и запуск ===
Создайте файл <code>.env</code> в который поместите следующие переменые:
<pre>
US_AMQP_DSN=amqp://имя_пользователя:пароль@адрес_хоста_rabbitmq:5672/%2f
USM_POLLER_SATELLITE_ID=id_вашего_satellite
USM_POLLER_LOGFILE=stdout
</pre>

Выполните тестовый запуск:
<pre>
sudo -H venv/bin/python worker.py
</pre>

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

Остановите работу поллера, запущенного вручную, комбинацией клавиш Ctrl+C. Придется подождать около 5 сек, пока поллер завершит все свои задачи и корректно закроет подключение к брокеру.

Из файла <code>.env</code> удалите строку с переменной <code>USM_POLLER_LOGFILE</code>. По умолчанию логи пишутся в файл /var/log/usm_poller/poller.log. Если вас не устраивает этот путь, то вместо удаления переменной, измените ее значение на нужный вам файл.

Скопируйте пример настроек супервизора и пример настроек ротации логов из подкаталога etc:
<pre>
sudo cp etc/usm_poller.conf-example /etc/supervisor/conf.d/usm_poller.conf
sudo cp etc/logrotate-example /etc/logrotate.d/usm_poller
</pre>

Отредактируйте файл /etc/supervisor/conf.d/usm_poller.conf. В нем измените путь к поллеру: вместо /var/www/userside/microservice/poller укажите /opt/poller или тот, куда вы скопировали поллер. Также укажите количество запускаемых копий в параметре numprocs. В зависимости от количества оборудования и количества задач, обслуживаемых сателлитом. Начните с 2 и по мере необходимости в будущем изменяйте это значение. Запускать сразу 15 копий нет смысла. К тому же, если ваш сателлит-сервер недостаточно мощный, то это может привести к деградации производительности.

Отредактируйте файл /etc/logrotate.d/usm_poller если вы изменили путь к логам в переменной окружения <code>USM_POLLER_LOGFILE</code> файла <code>.env</code>.

Перезапустите супервизор, чтобы он перечитал конфигурацию:
<pre>
sudo systemctl restart supervisor
</pre>

И спустя несколько секунд понаблюдайте за процессами, которые он контролирует - все копии поллера должны быть в состоянии RUNNING.
<pre>
sudo supervisorctl status
</pre>

На этом настройка закончена.

=== Обновление ===
Для обновления вам придется снова делать архив поллера с сервера USERSDIE и переносить его на сателлит-сервер, где разархивировать и снова устанавливать (обновлять) зависимости.

Для этого на сервере USERSIDE создайте архив:
<pre>
cd /var/www/userside/microserice
tar --exclude="venv" -czf usm_poller.tgz poller/
</pre>

Скопируйте его на сателлит сервер в каталог /opt и разархивируйте:
<pre>
tar xzf usm_poller.tgz
cd poller
</pre>

Обновите зависимости:
<pre>
sudo -H venv/bin/pip install -U pip wheel
sudo -H venv/bin/pip install -U -r requirements.txt
</pre>

Перезапустите супервизор:
<pre>
sudo supervisorctl restart usm_poller:*
sudo supervisorctl status
</pre>

FAQ. Ошибка "ICMP Socket permission error: allow ICMP without root privileges."

2025-05-12T07:12:00Z

Uscld2: Новая страница: «Ошибка с текстом <code>ICMP Socket permission error: allow ICMP without root privileges.</code> может возникать в usm_poller начиная с версии 3.19.18 и связана она с тем, что операционная система не разрешает использовать ICMP для непривилегированного пользователя. Начиная с версии 3.19.17 были внесе...»

Ошибка с текстом <code>ICMP Socket permission error: allow ICMP without root privileges.</code> может возникать в usm_poller начиная с версии 3.19.18 и связана она с тем, что операционная система не разрешает использовать ICMP для непривилегированного пользователя. Начиная с версии 3.19.17 были внесены изменения в usm_poller, позволяющие запускать эту службу от имени простого пользователя, что положительно сказывается на безопасности. Если вы столкнулись с такой ошибкой, то вам нужно проделать следующее:

1. Остановите службу поллера:
<pre>sudo supervisorctl stop usm_poller:*</pre>
2. Измените значение параметра <code>user</code> в файле конфигурации службы /etc/supervisor/conf.d/usm_poller.conf на www-data (или любой другой на ваше усмотрение, но не root)
3. Удалите лог-файл (или измените его владельца на такого же, как в п.2) /var/log/usm_poller/poller.log
4. Перечитайте конфигурацию супервизора (это действие также перезапустит и службу), затем проверьте, что служба запустилась и все ее копии находятся в состоянии RUNNING:
<pre>sudo systemctl restart supervisor
sudo supervisorctl status</pre>
(возможно между командами придется выждать паузу в 10...15 секунд).

Теперь вернитесь в интерфейс ERP USERSIDE и проверьте, не пропала ли ошибка. Если ошибка все еще присутствует (это может быть на относительно старых операционных системах), то нужно изменить значение параметра <core>net.ipv4.ping_group_range</code> в sysctl.

Для этого выполните команды:
<pre>echo 'net.ipv4.ping_group_range = 0 2147483647' | sudo tee -a /etc/sysctl.conf
sudo sysctl -p</pre>

Если вы столкнулись с ошибкой invalid argument, то отредактируйте файл /etc/sysctl.conf и измените значение 2147483647 на 65535 и снова выполните:
<pre>sudo sysctl -p</pre>

Теперь вернитесь в интерфейс ERP USERSIDE и проверьте, не пропала ли ошибка. Если ошибка все еще присутствует, обратитесь в техподдержку.

Частые вопросы

2025-05-12T07:01:41Z

Uscld2: /* Оборудование */

[[Frequently_Asked_Questions|en]] | [[Частые_вопросы|ru]]

== Карты и адреса ==
* [[FAQ. Использовать в работе одну карту или несколько карт|Использовать в работе одну карту или несколько карт]]

* [[FAQ. Проблемы с домами на карте|При добавлении дома на карту - карта перескакивает на совершенно другой город/область]]

* [[FAQ. Проблемы с переносом объектов на картах|Как перенести объекты с одной карты на другую?]]

* [[FAQ. Проблемы с картами|Карты периодически не отображаются]]

* [[FAQ. Проблемы при добавлении дома на карту покрытия|Проблемы при добавлении дома на карту покрытия. Ошибочная локация]]

* [[FAQ. Проблемы при добавлении дома на карту покрытия#Не выводится полигон для добавления дома|Проблемы при добавлении дома на карту покрытия. Не выводится полигон для добавления дома]]

* [[FAQ. Проблемы при поиске на карте покрытия|Проблема при поиске на карте покрытия. Ошибочная локация]]

* [[FAQ. Объекты на карте сместились|Объекты на карте сместились]]

* [[FAQ. Настройка размера иконок для собственных объектов на карте|Настройка размера иконок для собственных объектов на карте]]

* [[FAQ. Улица/город были переименованы. Как это изменить в USERSIDE?|Улица/город были переименованы. Как это изменить в USERSIDE?]]

== Файлы ==
* [[FAQ. Разрешенные расширения файлов|Как изменить разрешённые для загрузки расширения файлов]]

* [[FAQ. Проблемы с файлами|При прикреплении файлов - эти файлы не открываются]]

* [[FAQ. Ограничение на загружаемый файл|Как изменить ограничение на размер загружаемых файлов?]]

== Модули ==

* [[FAQ. Проблемы с модулем usm_asterisk|Проблемы с модулем usm_asterisk ''(нет всплывающих сообщений, звонков и т.п.)'']]

* [[FAQ. Запуск модулей под Windows|Как запускать perl-модули на компьютерах с OS Windows?]]

== Оборудование ==

* [[FAQ. Проблемы с активностью объектов|В списке оборудования - часть оборудования отображается красным цветов как неактивное. Открывает карточку оборудования - всё работает. Оборудование становится зелёным. Через время опять красное.]]

* [[FAQ. Активность ONU/ONT|ONU/ONT постоянно меняют статус с активного на неактивное и наоборот.]]

* [[FAQ. Влияние аппаратных или программных версий на опрос оборудования|Точно такая же модель оборудования, но с другой программной или аппаратной версией работает некорректно]]

* [[FAQ. Зависание OLT BDCOM при опросе списка ONU/ONT|Зависание OLT BDCOM при опросе списка ONU/ONT]]

* [[FAQ. Опрос оборудования ZTE OLT|Опрос оборудования ZTE OLT]]

* [[FAQ. Опрос оборудования CDATA OLT|Опрос оборудования CDATA OLT]]

* [[FAQ. Опрос оборудования BDCOM OLT|Опрос оборудования BDCOM OLT]]

* [[FAQ. Ошибка "ICMP Socket permission error: allow ICMP without root privileges."|Ошибка "ICMP Socket permission error: allow ICMP without root privileges."]]

== Прочее ==

* [[FAQ. Сообщение при установке "The entered URL ... could not be verified"|Сообщение при установке "The entered URL ... could not be verified"]]

* [[FAQ. Перенос USERSIDE на другой сервер|Перенос USERSIDE на другой сервер]]

* [[FAQ. Не работает планировщик|Сообщение на главной странице о том, что не работает планировщик]]

* [[FAQ. Бывший абонент становится обычным|При переводе абонента в категорию "Бывших абонентов" он через время вновь возвращается к обычным абонентам]]

* [[FAQ. Неверное время|Сообщения о неверном времени / Отображение неверного времени]]

* [[FAQ. Необходимые PHP-модули|Какие PHP-модули необходимо устанавливать?]]

* [[FAQ. Проблемы с отправкой электронной почты|Не работает отправка сообщений электронной почты из-под UserSide]]

* [[FAQ. Проблемы с кодировкой|Как сконвертировать базу данных в UTF-8?]]

* [[FAQ. Ошибка sql_mode=only_full_group|Ошибка "this is incompatible with sql_mode=only_full_group"]]

* [[FAQ. Ошибка ST_AsText|Ошибка "SQL-error N:1305: FUNCTION userside.ST_AsText does not exist"]]

* [[FAQ. База оборудования. Error during connect to UserSide Equipment Database (0)|Error during connect to UserSide Equipment Database (0)]]

* [[Tuning|Тонкая настройка PostgreSQL]]

* [[FAQ. Не запускается модуль "Module disabled in system - exit"|Не запускается модуль "Module disabled in system - exit"]]

* [[FAQ. Переход с network на полную редакцию|Переход с network на полную редакцию]]

* [[FAQ. Увеличение лимитов|Увеличение лимитов]]

* [[FAQ. Массовое удаление абонентов|Массовое удаление абонентов]]

* [[FAQ. Использование сканера штрихкодов|Использование сканера штрихкодов]]

* [[FAQ. Сброс пароля и разблокировка администратора|Сброс пароля и разблокировка администратора]]

* [[FAQ. Почему мои тикеты на доработку не выполняются|Почему мои тикеты на доработку не выполняются]]

* [[FAQ. Ошибка "Check installer version API Error 0 cURL error 60: SSL certificate problem: certificate has expired"|Ошибка "Check installer version API Error 0 cURL error 60: SSL certificate problem: certificate has expired"]]

* [[FAQ. Ошибки "502 Bad Gateway и 504 Gateway Time-out"|Ошибки "502 Bad Gateway и 504 Gateway Time-out"]]

* [[FAQ. The REDIS database used by another copy of the USERSIDE|Изменился URL USERSIDE, получаю ошибку The REDIS database used by another copy of the USERSIDE]]

* [[python-update|Обновление Python]]

* [[FAQ. Реверсивный прокси|Реверсивный прокси]]

Installation

2025-05-01T14:55:18Z

Uscld2: /* Setting */

<languages/>
[[Installation|en]] | [[Установка|ru]]

'''ATTENTION: These instructions are valid for ERP USERSIDE versions 3.19'''
* [[Installation for version 3.18|Instruction for version 3.18]]
* [[Installation for version 3.17|Instruction for version 3.11-3.17]]
* [[Installation for version 3.10 and earlier|Instruction for version 3.10 and earlier]].

== Description ==
For the sake of simplicity, the commands for the '''Linux Debian 12 (bookworm)''' operating system will be considered. For experienced system administrators, it should not be difficult to use similar commands for another operating system. If you do not feel confident in administering operating systems, we recommend you to use '''Debian''' or '''Ubuntu Server LTS'''. Because of their simplicity and because our technical support is much more familiar with Debian-like distributions. The likelihood of being able to tell you something not related to ERP USERSIDE, but related to operating system administration, will be much higher if you have Debian or a similar distribution based on it.

On the other hand, if you are an experienced system administrator and have skills and experience with Docker, it may be more convenient for you to use a ready-made environment based on Docker images that we have prepared specially, including everything you need to run ERP USERSIDE. In this case, you will not have to configure anything, except to perform simple Docker-bundle settings https://github.com/userside/userside-docker.

== Requirements ==
ERP USERSIDE requires various system applications and services such as PHP interpreter with a set of extensions, WEB server, database management system and others. This section will list such requirements depending on the version of ERP USERSIDE.

Also note that your operating system must be configured with the correct time zone and locale. The correct display of information and correct sorting depends on this.

The list of required PHP extensions contains all extensions that are not part of the PHP core. Some of these extensions may come with the core PHP package or as part of the php-common package, while others must be installed additionally.

=== 3.19 (current stable) ===
* PHP: 8.3
* PHP extensions: ctype, gd, json, libxml, mbstring, openssl, pdo, pdo_pgsql, posix, simplexml, snmp, sockets, zlib, pcntl
* Additional PHP extensions: ldap, soap
* Python: ''Requires Python3 of any currently supported version. The status of versions can be viewed here:"[https://devguide.python.org/versions/ Status of Python versions]". It is recommended to use a version with "security" or "bugfix" status. Versions marked as "end-of-life" are not supported. Versions marked as "feature" are not recommended.''
* Python modules: pip, venv
* PostgreSQL: 12+ (preferably 16)
* Redis: 5+ (preferably 7)
* RabbitMQ: 3.10+ (preferably 3.13)
* Supervisor

== Main agreements ==
The directory where ERP USERSIDE is installed is <code>/var/www/userside</code>. Inside this directory there should be a subdirectory public, which is the root directory for the WEB server. If you want to use a different directory for ERP USERSIDE, remember to make the appropriate corrections to all the examples in these instructions.

Create the directory:
sudo mkdir -p /var/www/userside/public
sudo chown -R www-data:www-data /var/www/userside

You will need to allocate a domain name for ERP USERSIDE. The examples below use userside.mycompany.com, but you will need to change it to your own. Write this domain name in /etc/hosts if it is different from the hostname of the installation.

== Installation of the required components ==
First install the utilities that will be required later in the installation process. They are required for any ERP USERSIDE program. You can copy the lines one at a time and paste them into the command line of your operating system.

Copy and paste the following lines in their entirety:
<pre>
sudo tee /etc/apt/sources.list.d/contrib-non-free.list << EOL
deb http://deb.debian.org/debian/ $(lsb_release -sc) contrib non-free non-free-firmware
EOL

sudo apt update
sudo apt full-upgrade -y
sudo apt install -y gnupg ca-certificates lsb-release debian-archive-keyring debian-keyring libsnmp-dev snmp-mibs-downloader
</pre>

=== PostgreSQL ===
==== Alternative official repository ====
We strongly recommend using the latest version of PostgreSQL, as this always has a positive impact on speed. Add the official Postgres repository to the system:
<pre>
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
</pre>
If you have a different operating system, you can find the necessary commands for it at [https://www.postgresql.org/download/ official PostgreSQL website].

==== Installation ====
'''Attention!''' Before installing PostgreSQL, your operating system must have your local locale and correct time zone set! This can be done later, but it will be much easier if it is done before installing PostgreSQL. Run the following command to make sure the correct locale is present:
locale -a

If your local locale is not among those listed, then install it. To do this, simply edit the /etc/locale.gen file by removing the comments before the line(s) with the desired locale, and then run the command:
sudo locale-gen

If you need to change the default locale, run:
sudo dpkg-reconfigure locales

To change the time zone, execute:
sudo timedatectl set-timezone Europe/Kyiv

Now you can move on to the PostgreSQL installation:
sudo apt install -y postgresql-16 postgresql-16-postgis-3

==== Setting ====
Create a user and database for ERP USERSIDE. The example below creates a user named userside and a database with the same name. If your locale is not uk_UA, remember to change the command. The PostGis extension needed to work with geographic data is then connected to the database. After doing the first line, you will need to enter the password for the new user twice - make a note of this password, you will need it later to set up ERP USERSIDE
<pre>
sudo -u postgres createuser userside -P
sudo -u postgres createdb -e -E "UTF-8" -l "uk_UA.UTF-8" -O userside -T template0 userside
sudo -u postgres psql -d userside -c "CREATE EXTENSION postgis"
</pre>

If your PostgreSQL is installed '''on another server''', you will need to make corrections to the postgresql.conf and pg_hba.conf files located in the /etc/postgresql/16/main/ directory. In the postgresql.conf file, you must uncomment and change the value of the parameter <code>listen_addresses</code>, specifying there all IP addresses of the server interfaces on which it can accept connections to PostgreSQL. In the pg_hba.conf file you need to add a line at the very end, similar to the previous ones, indicating from which address the ERP USERSIDE user can connect. But if your PostgreSQL is located on the same server as USERSIDE - there is no need to make any adjustments to these files.

=== Redis ===
The Debian 12 standard repository includes Redis version 7.0.15. This version is suitable for running ERP USERSIDE.

==== Installation ====
sudo apt install -y redis-server

==== Setting ====
By default Redis accepts connections without a password, but we strongly recommend setting a password. Since the password is transmitted in the clear (Redis does not provide encryption because it focuses on speed of request processing and extra steps like encryption are not applied), you need to create a really long and complex password, for example, using the '''openssl''' utility as follows:

openssl rand --hex 32

The output will be a random set of 32 bytes in 16-character form, which you will use as a password. Next, you will need to substitute this generated string in place of the word '''MYPASSWORDHERE'''. Write it down. Then you will specify this string as the Redis password in the settings.

Specify the generated passphrase hash in the Redis configuration file:

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

where instead of '''MYPASSWORDHERE''' specify the hash of the passphrase received earlier.

You should also disable timeout (on some versions of Redis it is enabled):

sudo sed -i 's@^timeout .*@timeout 0@' /etc/redis/redis.conf

Restart Redis and make sure it works (should get PONG in response):
<pre>
sudo systemctl restart redis
redis-cli -h 127.0.0.1 -p 6379 -a MYPASSWORDHERE ping
</pre>

=== RabbitMQ ===
The Debian 12 standard repository includes an older version of RabbitMQ 3.10. You can use it - it is supported. However, this version is relatively old and your best bet is to install a newer version from alternative repositories. The [https://www.rabbitmq.com/install-debian.html official RabbitMQ website] has fairly detailed information on installing RabbitMQ for each operating system.

==== Adding alternative repositories ====
Copy and paste the following block in its entirety into the command line
<pre>
curl -1sLf https://dl.cloudsmith.io/public/rabbitmq/rabbitmq-erlang/gpg.E495BB49CC4BBE5B.key | sudo gpg --dearmor | sudo tee /usr/share/keyrings/rabbitmq-erlang-archive-keyring.gpg > /dev/null
curl -1sLf https://dl.cloudsmith.io/public/rabbitmq/rabbitmq-server/gpg.9F4587F226208342.key | sudo gpg --dearmor | sudo tee /usr/share/keyrings/rabbitmq-server-archive-keyring.gpg > /dev/null

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
</pre>

==== Installation ====
Make sure that /etc/hosts has an entry for your hostname. The lack of such an entry (for example, if you changed the hostname after installation) is a major error that occurs when installing RabbitMQ. So it is better to make sure again that there is an entry for the hostname.
<pre>
sudo apt install -y erlang-base \
erlang-asn1 erlang-crypto erlang-eldap erlang-ftp erlang-inets \
erlang-mnesia erlang-os-mon erlang-parsetools erlang-public-key \
erlang-runtime-tools erlang-snmp erlang-ssl \
erlang-syntax-tools erlang-tftp erlang-tools erlang-xmerl

sudo apt install rabbitmq-server -y --fix-missing
</pre>

==== Installation of necessary add-ons ====
Do the next two lines one at a time!
<pre>
sudo rabbitmq-plugins enable rabbitmq_management --offline

sudo rabbitmq-plugins enable rabbitmq_web_stomp --offline
</pre>

==== Setting ====
Copy and paste the following block in its entirety:
<pre>
sudo tee /etc/rabbitmq/rabbitmq.conf << EOF
listeners.tcp.default = 5672

web_stomp.port = 15674
web_stomp.cowboy_opts.max_keepalive = 60
EOF
</pre>

Now you need to create users. We recommend using '''three different users''': for server administration (full rights), for userside and modules (full rights but no administrative rights) and the web-stomp user for websocket (minimal rights to read certain broker objects). But you can only create two: an admin user, which will also be used for userside, and a user for websocket. These must necessarily be at least two different users, since the password for the websocket user is passed to the browser and can be easily read by the user. The following will show an example for the recommended three users.

Create a '''user for administration''' RabbitMQ. This example uses the username '''admin''' and password '''admin_password'''.
A tag <code>administrator</code> is assigned to the user immediately after creation, giving the user maximum administrator rights and then set permissions for vhost <code>/</code> allowing full access to configure, write and read everything within that vhost*.
<pre>
sudo rabbitmqctl add_user "admin" "admin_password"
sudo rabbitmqctl set_user_tags "admin" "administrator"
sudo rabbitmqctl set_permissions -p "/" "admin" ".*" ".*" ".*"
</pre>

Create a '''user on behalf of which ERP USERSIDE''' and modules will run. Example for the user name '''userside''' (you do not need to give admin rights to this user):
<pre>
sudo rabbitmqctl add_user "userside" "system_password"
sudo rabbitmqctl set_user_tags "userside" "monitoring"
sudo rabbitmqctl set_permissions -p "/" "userside" ".*" ".*" ".*"
</pre>

Create a '''WebSTOMP user''' . You will need it to use notifications via WebSocket. Instead of '''websock-user''' you can specify a different user name. Instead of '''password_websocket''' specify your password, but this password will be passed in the clear to the browser, so don't make it similar to other passwords:
<pre>
sudo rabbitmqctl add_user "websock-user" "password_websocket"
sudo rabbitmqctl set_permissions -p "/" "websock-user" "^erp-stomp:id-.*" "" "^erp-stomp:id-.*"
</pre>

Attention!: You will need to specify the WebSTOMP username and password in the settings in the USERSIDE interface (Menu: Settings - Main - Websocket).

''* vhost - is a virtual host within RabbitMQ that allows different applications to differentiate between different uses of the same server. Like, for example, different databases on the same DBMS server. The default vhost is named / and almost always this is enough for you. But if you plan, for example, to run multiple copies of ERP USERSIDE on the same server, then for each copy you will need to create a different vhost and, accordingly, users for it. Please refer to [https://www.rabbitmq.com/vhosts.html official manual] for more details.‘’

Restart the rabbitmq service:
<pre>
sudo systemctl restart rabbitmq-server
</pre>

==== Management ====
One of the commands above installs a management module in RabbitMQ that provides a convenient WEB interface to monitor, diagnose, and manage the RabbitMQ server. With this module you can monitor the server, keep track of the number of messages in queues and other statuses. All this can be done using the console utility as well <code>rabbitmqctl</code>, but using the WEB-interface can be much clearer and more convenient.

By default, the WEB management interface is available at http://userside.mycompany.com:15672. We recommend using a firewall to restrict access to this control interface.

More details about the control module can be [https://www.rabbitmq.com/management.html read on the official RabbitMQ website].

=== PHP ===
==== Alternative repository ====
<pre>
sudo curl -sSLo /usr/share/keyrings/deb.sury.org-php.gpg https://packages.sury.org/php/apt.gpg
sudo sh -c 'echo "deb [signed-by=/usr/share/keyrings/deb.sury.org-php.gpg] https://packages.sury.org/php/ $(lsb_release -sc) main" > /etc/apt/sources.list.d/php.list'
sudo apt update
</pre>

==== Installation ====
Execute the following commands:
<pre>
sudo apt install -y php8.3-{fpm,cli,common,curl,intl,mbstring,opcache,pgsql,readline,xml,zip,snmp,gd}
</pre>

If you plan to use LDAP, you need to install the php-ldap extension:
<pre>
sudo apt install -y php8.3-ldap
</pre>

If you plan to use TurboSMS to send SMS, you will also need the php-soap extension:
<pre>
sudo apt install -y php8.3-soap
</pre>

==== Setting ====
The following are commands that make changes to the configuration files.
<pre>
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
</pre>

=== NGINX ===
==== Alternative official repository ====
The version of NGINX supplied in the Debian repository is fully usable and there is no need to add an alternative repository. However, if you want to always have the latest version, run the following lines to add the official nginx repository to your operating system:
<pre>
curl https://nginx.org/keys/nginx_signing.key | gpg --dearmor \
| sudo tee /usr/share/keyrings/nginx-archive-keyring.gpg >/dev/null
echo "deb [signed-by=/usr/share/keyrings/nginx-archive-keyring.gpg] \
http://nginx.org/packages/debian `lsb_release -cs` nginx" \
| sudo tee /etc/apt/sources.list.d/nginx.list
echo -e "Package: *\nPin: origin nginx.org\nPin: release o=nginx\nPin-Priority: 900\n" \
| sudo tee /etc/apt/preferences.d/99nginx
sudo apt update
</pre>

If you have a different operating system, you can find the necessary commands for it on the official NGINX website: https://docs.nginx.com/nginx/admin-guide/installing-nginx/installing-nginx-open-source/

==== Installation ====
<pre>
sudo apt install -y nginx
</pre>

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

The following configuration example assumes that the ERP USERSIDE will be set to the system's default directory <code>/var/www/userside</code>. If you wish to install ERP USERSIDE in a different directory, please remember to fix it in all subsequent examples. In order not to make a mistake, we recommend to use exactly the directory <code>/var/www/userside</code>.

Now edit the file /etc/nginx/conf.d/default.conf. Or delete it and create a file named /etc/nginx/conf.d/userside.conf. In either case, regardless of your choice, the contents of the file should be as follows (instead of userside.mycompany.com, specify your domain name):
<pre>
server {
listen 80 default_server;
server_name userside.mycompany.com;
charset utf-8;
client_max_body_size 100M;

access_log /var/log/nginx/userside-access.log;
error_log /var/log/nginx/userside-error.log;

root /var/www/userside/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|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; }
}
</pre>

You may also want to configure SSL and something else. This topic is beyond the scope of this manual.

If you have installed RabbitMQ '''on another server''', or changed the value of the WebSTOMP port from 15674 to some other, then specify the IP address of the server with RabbitMQ and the port number in the line <code>proxy_pass http://127.0.0.1:15674/ws;</code>. The protocol must remain http. The path must remain /ws.

Check the configuration and if it is ok restart nginx:
sudo nginx -t && sudo nginx -s reload

=== Python ===
''Requires Python3 of any currently supported version. The status of versions can be viewed here:"[https://devguide.python.org/versions/ Status of Python versions]". It is recommended to use a version with "security" or "bugfix" status. Versions marked as "end-of-life" are not supported. Versions marked as "feature" are not recommended.''

If you have an unsupported version ("end-of-life") installed on your host, you should be sure to [[Python-update_EN|install additionally]] a more recent version of Python.

==== Installing the required packages ====
sudo apt install -y python3-dev python3-pip python3-venv libffi-dev pkg-config

=== Supervisor ===
sudo apt install -y supervisor

== Downloading and launching the installer ==

See also: [[Installer|Installer Help]]

1. navigate to the system catalogue
cd /var/www/userside

2. download the installer script
sudo -u www-data php -r "copy('https://my.userside.eu/install', 'userside_install.phar');"

3. run installer
sudo -u www-data php userside_install.phar install

During operation, the installer verifies compliance with technical requirements, requests access parameters, and checks connections to server services.

You can enter any ERP USERSIDE version number available to you for installation. To do this, you can enter the version number from the list (it contains only the latest version of each branch) or enter the entire version number if it is not on the list.

When the installer finishes, a message will be displayed indicating that the installation was successful.

If you did not install as a web server user, be sure to make that user the owner of all userside files recursively after the installation is complete!

sudo chown -R www-data:www-data /var/www/userside
sudo chmod -R u=rwX,g=rwX,o=r /var/www/userside

== Setting up after installation ==

=== Configuration of system services ===
After installation, copy the sample configuration files of the system services and, if necessary, customise them (for example, specify the path to the userside directory if it is different from /var/www/userside). Run the commands:
<pre>
sudo cp etc/us-core-worker.conf-example /etc/supervisor/conf.d/us-core-worker.conf
sudo cp microservice/poller/etc/usm_poller.conf-example /etc/supervisor/conf.d/usm_poller.conf
sudo cp etc/logrotate-example /etc/logrotate.d/userside
sudo cp microservice/poller/etc/logrotate-example /etc/logrotate.d/usm_poller
sudo cp etc/crontab-example /etc/cron.d/userside
</pre>

=== Installation of necessary dependencies for usm_poller ===
Create a venv virtual environment for python and install the dependent modules as shown below:
<pre>
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
</pre>

=== Running the supervisor ===
The Supervisor controls the operation of the services specified in its configuration. To launch the supervisor, run the following:
<pre>
sudo systemctl restart supervisor
</pre>
After the supervisor is launched, after a few seconds you can observe the state of all the services it controls. All services must be in the RUNNING state:
<pre>
sudo supervisorctl status
</pre>

== Immediately after the installation ==
This completes the installation of ERP USERSIDE. Now perform the following steps:
* Open the system page '''<nowiki>http://userside.mydomain.com/</nowiki>''' and login ''(default username: Admin, password: 1234)''.
* Configure Websocket under: Settings - Main - WebSocket. Enable and enter the username and password of the WebStomp user you created earlier under RabbitMQ.
* Make main settings in the section: [[Settings_-_Main|Settings - Main]].
* Configure interaction with [[Supported_billings|billing]] according to the [[Setting_up_interactions_with_a_billing|instructions]].
* Read the instructions on the page: [[Start_EN|Where to start?]].
* Configure the [[UserSide_API_Key|API Key]].

== System upgrade ==
We try to do our best to ensure that the likelihood of an end-to-end upgrade from any version to the latest version is successful. However, it sometimes happens that due to some ancient problems with the database structure that never prevented you from working before, a situation may arise in which an end-to-end upgrade is not possible. In this case you will have to upgrade step by step to each next latest version. For example, from 3.14.80 first to 3.15.60, then to 3.16.39, and so on.

Before upgrading, be sure to read about all the changes you need to make to upgrade for each version that lies between yours and the one you are going to upgrade to.

We recommend making a copy of your system to safely perform the upgrade. Refer to [[HOWTO: USERSIDE cloning]]. You can always delete the copy and start over. This is easy and safe. But if you wish to upgrade a running system, perform it at times of least stress, with time to spare for disaster recovery if something goes wrong. Always be sure to back up your database and files before upgrading. If an update is interrupted, especially during the data migration phase, there is a risk that it will be very difficult or even impossible to restore the data correctly. In general, the responsibility for having an up-to-date backup lies entirely with you.

==== Upgrade process ====
We strongly recommend performing test upgrades on a [[HOWTO: USERSIDE cloning|copy of the system]].

To perform an upgrade, run the installer in install mode and follow the instructions:
<pre>
cd /var/www/userside
sudo -u www-data php userside_install.phar install
</pre>

After upgrading the USERSIDE, you should be sure to upgrade the usm_poller dependencies:
<pre>
cd /var/www/userside/microservice/poller
sudo -H venv/bin/pip install -U pip
sudo -H venv/bin/pip install -U -r requirements.txt
</pre>

Now we need to restart all the services that are supervised by the supervisor and make sure that all of them start and are in the RUNNING state:
<pre>
sudo supervisorctl restart all
sudo supervisorctl status
</pre>

== System maintenance ==
To keep the system up to date and to ensure reliable operation in the future, it is recommended that you follow a few simple steps:
* periodically back up the database
* periodically create a backup copy of uploaded files (this can be done simply by archiving the /var/www/userside/var/attachments directory and the .env file)
* periodically monitor server performance (using htop, atop) and the RabbitMQ broker and make decisions about scaling fpm pools, kernel background processes and microservices

=== Backup ===
Set up periodic backups of the database and user files. Preferably at least once a day when the server is least loaded. In PostgreSQL, there are two ways to back up the database: dump and sql-script. Each of them has its own advantages and disadvantages. The first one creates a secure dump of the entire database, while the second one creates a SQL script that can restore both structure and data. We recommend referring to [https://www.postgresql.org/docs/current/app-pgdump.html documentation on how to use the pg_dump command] for a more suitable method or set of parameters for you.

Below are two commands for creating a database backup - choose one of them and add it to your crontab:
<pre>
# 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
</pre>

To create a minimal backup of '''files''' you can use the following command (for version 3.15 and later):
sudo tar -czf /backup/userside.tgz .env common/config/settings.json var/attachments
These files together with the database will be enough to restore USERSIDE. But you can back up the entire /var/www/userside directory for more reliability.

=== Restoring from a backup ===
The pg_restore command is used to restore from a dump. [https://postgrespro.ru/docs/postgresql/13/app-pgrestore Documentation on using pg_restore]. The psql utility is used to restore from a SQL script. [https://www.postgresql.org/docs/current/app-psql.html Documentation on using psql].

Before restoring the database from a backup, you must be sure to stop USERSIDE.

1. Stop cron userside and all modules
<pre>
mkdir -p ~/cron
sudo mv /etc/cron.d/userside ~/cron
sudo mv /etc/cron.d/userside-modules ~/cron
</pre>
2. Stop running background services
<pre>
sudo supervisorctl stop all
</pre>
3. Stop php-fpm from running
<pre>
sudo systemctl stop php8.3-fpm
</pre>
Only then can you proceed to restore the database from a backup copy.

==== SQL-script ====
To restore a database from a backup as a SQL script, you must first recreate the database and then restore to an empty backup database:
<pre>
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
</pre>

==== DUMP ====
The dump contains the entire database with all its elements. Therefore, before restoring a database from a dump, it must not exist on the server - delete the database before restoring from a dump. It is also important that the database user (the owner of all items) already exists - create it before restoring if you are restoring the database on a new server where the required user does not exist yet.

Also note that the dump structure may not be compatible between different versions of PostgreSQL. This is not necessarily the case, but it is likely.

To restore from the dump, use the commands:
<pre>
sudo -u postgres dropdb userside
sudo -u postgres pg_restore --clean --if-exists --create --exit-on-error --dbname=postgres userside.dump
</pre>
Note that the database name in the command must be '''postgres''', because the entire database is restored from the dump, not its contents.

==== After restoring the database ====
After restoring the database in any way, you must clear the ERP USERSIDE cache, as the cache now contains different data from the database. Go to the /var/www/userside directory and run the clear cache command (first, if a password is used, or second, if it is not used):
<pre>
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
</pre>
Restore services that were stopped before performing the backup:
<pre>
sudo mv ~/cron/* /etc/cron.d
sudo supervisorctl start all
sudo systemctl start php8.3-fpm
</pre>
Run the restore command to make the system files match the database version and check the system for file integrity.
<pre>
cd /var/www/userside
sudo -u www-data php userside_install.phar repair
</pre>

Установка

2025-05-01T14:55:02Z

Uscld2: /* Настройка */

<languages/>
[[Installation|en]] | [[Установка|ru]]

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

== Описание ==
В целях упрощения будут рассмотрены команды для операционной системы '''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 любой поддерживаемой на данный момент версии. Статус версий можно посмотреть здесь: "[https://devguide.python.org/versions/ 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 - <code>/var/www/userside</code>. Внутри этого каталога должен быть подкаталог 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. Вы можете копировать строки по одной и вставлять их в командную строку вашей операционной системы.

Следующие строки скопируйте и вставьте целиком:
<pre>
sudo tee /etc/apt/sources.list.d/contrib-non-free.list << EOL
deb http://deb.debian.org/debian/ $(lsb_release -sc) contrib non-free non-free-firmware
EOL

sudo apt update
sudo apt full-upgrade -y
sudo apt install -y gnupg ca-certificates lsb-release debian-archive-keyring debian-keyring libsnmp-dev snmp-mibs-downloader
</pre>

=== PostgreSQL ===
==== Альтернативный официальный репозиторий ====
Мы настоятельно рекомендуем использовать последнюю версию PostgreSQL, так как это всегда положительно сказывается на скорости работы. Добавьте в систему официальный репозиторий Postgres:
<pre>
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
</pre>
Если у вас другая операционная система, вы можете найти необходимые команды для нее на [https://www.postgresql.org/download/ официальном сайте 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
<pre>
sudo -u postgres createuser userside -P
sudo -u postgres createdb -e -E "UTF-8" -l "uk_UA.UTF-8" -O userside -T template0 userside
sudo -u postgres psql -d userside -c "CREATE EXTENSION postgis"
</pre>

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

=== 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):
<pre>
sudo systemctl restart redis
redis-cli -h 127.0.0.1 -p 6379 -a MYPASSWORDHERE ping
</pre>

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

==== Добавление альтернативных репозиториев ====
Следующий блок скопируйте и вставьте целиком в командную строку
<pre>
curl -1sLf https://dl.cloudsmith.io/public/rabbitmq/rabbitmq-erlang/gpg.E495BB49CC4BBE5B.key | sudo gpg --dearmor | sudo tee /usr/share/keyrings/rabbitmq-erlang-archive-keyring.gpg > /dev/null
curl -1sLf https://dl.cloudsmith.io/public/rabbitmq/rabbitmq-server/gpg.9F4587F226208342.key | sudo gpg --dearmor | sudo tee /usr/share/keyrings/rabbitmq-server-archive-keyring.gpg > /dev/null

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
</pre>

==== Установка ====
Убедитесь, что в /etc/hosts есть запись для имени вашего хоста. Отсутствие такрой записи (например, если вы изменили имя хоста после инсталляции) является основной ошибкой, возникающей при установке RabbitMQ. Так что лучше еще раз убедитесь, что запись соответствующая имени хосту имеется.
<pre>
sudo apt install -y erlang-base \
erlang-asn1 erlang-crypto erlang-eldap erlang-ftp erlang-inets \
erlang-mnesia erlang-os-mon erlang-parsetools erlang-public-key \
erlang-runtime-tools erlang-snmp erlang-ssl \
erlang-syntax-tools erlang-tftp erlang-tools erlang-xmerl

sudo apt install rabbitmq-server -y --fix-missing
</pre>

==== Установка необходимых дополнений ====
Следующие две строки выполняйте по одной за раз!
<pre>
sudo rabbitmq-plugins enable rabbitmq_management --offline

sudo rabbitmq-plugins enable rabbitmq_web_stomp --offline
</pre>

==== Настройка ====
Скопируйте и вставьте целиком следующий блок:
<pre>
sudo tee /etc/rabbitmq/rabbitmq.conf << EOF
listeners.tcp.default = 5672

web_stomp.port = 15674
web_stomp.cowboy_opts.max_keepalive = 60
EOF
</pre>

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

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

Создайте '''пользователя, от имени которого будут работать ERP USERSIDE''' и модули. Пример для имени пользователя '''userside''' (наделять админскими правами этого пользователя не нужно):
<pre>
sudo rabbitmqctl add_user "userside" "пароль_системы"
sudo rabbitmqctl set_user_tags "userside" "monitoring"
sudo rabbitmqctl set_permissions -p "/" "userside" ".*" ".*" ".*"
</pre>

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

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

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

Перезапустите службу rabbitmq:
<pre>
sudo systemctl restart rabbitmq-server
</pre>

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

По умолчанию WEB-интерфейс управления доступен по адресу http://userside.mycompany.com:15672. Рекомендуем использовать фаервол, чтобы ограничить доступ к этому интерфейсу управления.

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

=== PHP ===
==== Альтернативный репозиторий ====
<pre>
sudo curl -sSLo /usr/share/keyrings/deb.sury.org-php.gpg https://packages.sury.org/php/apt.gpg
sudo sh -c 'echo "deb [signed-by=/usr/share/keyrings/deb.sury.org-php.gpg] https://packages.sury.org/php/ $(lsb_release -sc) main" > /etc/apt/sources.list.d/php.list'
sudo apt update
</pre>

==== Установка ====
Выполните следующие команды:
<pre>
sudo apt install -y php8.3-{fpm,cli,common,curl,intl,mbstring,opcache,pgsql,readline,xml,zip,snmp,gd}
</pre>

Если вы планируете использовать LDAP, необходимо установить расширение php-ldap:
<pre>
sudo apt install -y php8.3-ldap
</pre>

Если вы планируете использовать отправку SMS используя TurboSMS, также понадобится расширение php-soap:
<pre>
sudo apt install -y php8.3-soap
</pre>

==== Настройка ====
Далее приведены команды, вносящие изменения в файлы конфигурации.
<pre>
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
</pre>

=== NGINX ===
==== Альтернативный официальный репозиторий ====
Версия NGINX, поставляемая в репозитории Debian, полностью подходит для использования и нет необходимости в добавлении альтернативного репозитория. Однако, если вам хочется всегда иметь последнюю версию, то выполните следующие строки, чтобы добавить в операционную систему официальный репозиторий nginx:
<pre>
curl https://nginx.org/keys/nginx_signing.key | gpg --dearmor \
| sudo tee /usr/share/keyrings/nginx-archive-keyring.gpg >/dev/null
echo "deb [signed-by=/usr/share/keyrings/nginx-archive-keyring.gpg] \
http://nginx.org/packages/debian `lsb_release -cs` nginx" \
| sudo tee /etc/apt/sources.list.d/nginx.list
echo -e "Package: *\nPin: origin nginx.org\nPin: release o=nginx\nPin-Priority: 900\n" \
| sudo tee /etc/apt/preferences.d/99nginx
sudo apt update
</pre>

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

==== Установка ====
<pre>
sudo apt install -y nginx
</pre>

==== Настройка ====
<pre>
sudo sed -i "s@^user.*;@user www-data www-data;@" "/etc/nginx/nginx.conf"
sudo systemctl restart nginx
</pre>

Следующий пример настройки подразумевает, что ERP USERSIDE будет установлен в стандартный каталог системы <code>/var/www/userside</code>. Если вы желаете установить ERP USERSIDE в другой каталог, пожалуйста, не забывайте исправлять его во всех последующих примерах. Чтобы не ошибиться, мы рекомендуем использовать именно каталог <code>/var/www/userside</code>.

Теперь отредактируйте файл /etc/nginx/conf.d/default.conf. Либо удалите его и создайте файл с именем /etc/nginx/conf.d/userside.conf. В любом случае, не зависимо от вашего выбора, содержимое файла должно быть следующим (вместо userside.mycompany.com укажите свое доменное имя):
<pre>
server {
listen 80 default_server;
server_name userside.mycompany.com;
charset utf-8;
client_max_body_size 100M;

access_log /var/log/nginx/userside-access.log;
error_log /var/log/nginx/userside-error.log;

root /var/www/userside/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|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; }
}
</pre>

Также, возможно, вы захотите настроить SSL и что-либо еще. Эта тема выходит за рамки данной инстуркции.

Если Вы установили RabbitMQ '''на другом сервере''', либо изменили значение порта WebSTOMP с 15674 на какой-то другой, то укажите IP-адрес сервера с RabbitMQ и номер порта в строке <code>proxy_pass http://127.0.0.1:15674/ws;</code>. Протокол должен оставаться http. Путь должен оставаться /ws.

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

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

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

==== Установка необходимых пакетов ====
sudo apt install -y python3-dev python3-pip python3-venv libffi-dev pkg-config

=== Supervisor ===
sudo apt install -y supervisor

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

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

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

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

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

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

Вы можете ввести любой доступный вам номер версии 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). Выполните команды:
<pre>
sudo cp etc/us-core-worker.conf-example /etc/supervisor/conf.d/us-core-worker.conf
sudo cp microservice/poller/etc/usm_poller.conf-example /etc/supervisor/conf.d/usm_poller.conf
sudo cp etc/logrotate-example /etc/logrotate.d/userside
sudo cp microservice/poller/etc/logrotate-example /etc/logrotate.d/usm_poller
sudo cp etc/crontab-example /etc/cron.d/userside
</pre>

=== Установка необходимых зависимостей для usm_poller ===
Создайте виртуальное окружение venv для python и установите зависимые модули, как показано далее:
<pre>
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
</pre>

=== Запуск супервизора ===
Супервизор контролирует работу служб, указанных в его конфигурации. Для запуска супервизора выполните:
<pre>
sudo systemctl restart supervisor
</pre>
После запуска супервизора, спустя несколько секунд можно понаблюдать за состоянием всех контролируемых им служб. Все службы должны быть в состоянии RUNNING:
<pre>
sudo supervisorctl status
</pre>

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

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

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

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

==== Процесс обновления ====
Мы настоятельно рекомендуем выполнять тестовые обновления на [[HOWTO:_Клонирование_USERSIDE|копии системы]].

Для проведения обновления запустите инсталлятор в режиме install и следуйте инструкциям:
<pre>
cd /var/www/userside
sudo -u www-data php userside_install.phar install
</pre>

После обновления USERSIDE нужно обязательно обновить зависимости usm_poller:
<pre>
cd /var/www/userside/microservice/poller
sudo -H venv/bin/pip install -U pip
sudo -H venv/bin/pip install -U -r requirements.txt
</pre>

Теперь нужно перезапустить все службы, которолируемые супервизором и проследить чтобы все они запустились и были в состоянии RUNNING:
<pre>
sudo supervisorctl restart all
sudo supervisorctl status
</pre>

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

=== Резервное копирование ===
Установите периодическое резервное копирование базы данных и пользовательских файлов. Желательно минимум раз в сутки в моменты наименьшей нагрузки на сервер. В PostgreSQL существует два способа создать резервную копию базы данных: dump и sql-script. У каждого из них есть свои преимущества и недостатки. Первый создает безопасный дамп базы данных целиком, а второй создает SQL-скрипт, выполняя который можно восстановить как структуру так и данные. Рекомендуем обратиться к [https://www.postgresql.org/docs/current/app-pgdump.html документации по использованию команды pg_dump] для выбора более подходящего для вас способа или набора параметров.

Ниже приведены две команды для создания резервной копии базы данных — выбирайте одну из них и добавляйте в ваш crontab:
<pre>
# 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
</pre>

Для создания минимальной резервной копии '''файлов''' можно использовать следующую команду (для версии 3.15 и новее):
sudo tar -czf /backup/userside.tgz .env common/config/settings.json var/attachments
Этих файлов вместе с базой данных будет достаточно для восстановления работы USERSIDE. Но вы можете выполнять резервное копирование всего каталога /var/www/userside для большей надежности.

=== Восстановление из резервной копии ===
Для восстановления из дампа используется команда pg_restore. [https://postgrespro.ru/docs/postgresql/13/app-pgrestore Документация по использованию pg_restore]. Для восстановления из SQL-скрипта используется утилита psql. [https://www.postgresql.org/docs/current/app-psql.html Документация по использованию psql].

Перед восстановлением базы данных из резервной копии нужно обязательно остановить работу USERSIDE.

1. Остановить cron userside и всех модулей
<pre>
mkdir -p ~/cron
sudo mv /etc/cron.d/userside ~/cron
sudo mv /etc/cron.d/userside-modules ~/cron
</pre>
2. Остановить работу фоновых служб
<pre>
sudo supervisorctl stop all
</pre>
3. Остановить работу php-fpm
<pre>
sudo systemctl stop php8.3-fpm
</pre>
Только после этого можно приступать к восстановлению базы данных из резервной копии.

==== SQL-script ====
Для восстановления БД из резервной копии в виде SQL-скрипта, сначала нужно пересоздать базу данных, а затем восстановить в пустую базу данных резервную копию:
<pre>
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
</pre>

==== DUMP ====
Дамп содержит целиком базу данных со всеми ее элементами. Поэтому перед восстановлением базы данных из дампа её не должно существовать на сервере — удалите базу данных перед восстановлением из дампа. Также важно, чтобы пользователь базы данных (владелец всех элементов) уже существовал — создайте его перед восстановлением, если вы восстанавливаете базу данных на новом сервере, где нужного пользователя еще нет.

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

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

==== После восстановления базы данных ====
После восстановления базы данных любым способом, необходимо очистить кэш ERP USERSIDE, т.к. в кэше теперь находятся данные, отличные от данных в базе. Перейтите в каталог /var/www/userside и выполните команду очистки кэша (первую, если используется пароль или вторую, если не используется):
<pre>
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
</pre>
Восстановите работу служб, которые были остановлены перед выполнением резервной копии:
<pre>
sudo mv ~/cron/* /etc/cron.d
sudo supervisorctl start all
sudo systemctl start php8.3-fpm
</pre>
Выполните команду восстановления, чтобы файлы системы соответствовали версии базы данных и проверить систему на целостность файлов.
<pre>
cd /var/www/userside
sudo -u www-data php userside_install.phar repair
</pre>

HOWTO: Обновление версии PostgreSQL

2025-04-13T17:47:10Z

Uscld2: /* Проверить работу USERSIDE */

[[HOWTO:_PostgreSQL_version_upgrade|en]] | [[HOWTO:_Обновление_версии_PostgreSQL|ru]]

В данном разделе описана процедура обновления PostgreSQL ''между основными версиями'' (например, с версии 11 на версию 16).

Обновление внутри версии (например, с версии 16.1 на версию 16.2) ''происходит автоматически и не требует дополнительных действий''.

'''Рекомендуем ознакомиться с официальными инструкциями по обновлению''' на сайте [https://www.postgresql.org/docs/current/upgrading.html postgresql.org].

В дистрибутиве Debian и основанных на нем существует пакет [https://packages.debian.org/sid/postgresql-common postgresql-common], устанавливаемый автоматически при установке пакета PostgreSQL. В состав postgresql-common входят инструменты, упрощающие работу с кластерами баз данных PostgreSQL. В том числе и обновление кластеров БД.

Кластером баз данных ([https://www.postgresql.org/docs/current/glossary.html Database cluster]) в PostgreSQL называется экземпляр сервера вместе со всеми обслуживаемыми БД, а не распределенную систему, как может показаться.

В следующем примере будет показано обновление кластера БД с версии 11 на версию 16 используя инструменты из пакета '''postgresql-common'''.

== Порядок обновления ==
# Остановить USERSIDE.
# Обновить текущую версии postgresql в пределах основной версии (например, с 11.5 до 11.22).
# Обновить расширение postgis до самой последней версии (например, с 2.5 до 3.3.4). Также обязательно обновить расширение и в самой базе данных.
# Установить новую версию postgresql не удаляя старой (например 16.1)
# Сделать запасную резервную копию базы данных и настроек
# Удалить кластер БД, созданный автоматически сценарием при установке новой версии
# Выполнить обновление кластера БД старой версии до кластера новой версии
# Проверить работу USERSIDE
# Удалить кластер БД старой версии, устаревшие пакеты и запасные резервные копии

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

[https://asciinema.org/a/do2AE0z30mg5JLIuI9zhGTPoR Посмотреть видеоинструкцию на asciinema].

== Пошаговая инструкция ==
SQL-запросы с оператором <code>SELECT</code>, приведенные далее, необходимы для определения текущих установленных версий в качестве справочной информации.

=== Остановить USERSIDE ===
<pre>
sudo supervisorctl stop all
sudo systemctl stop php8.3-fpm
</pre>
Версия php указана для примера. Используйте ту, что испльзуется у вас.

Закомментируйте запуск всех модулей и userside в crontab.

=== Обновить текущую версии postgresql в пределах основной версии ===
Проверить текущие версии. Обновить текущие пакеты PostgreSQL и PostGIS:
<pre>
sudo -u postgres psql -d userside -A -t -c "SELECT VERSION()"
sudo -u postgres psql -d userside -A -t -c "SELECT PostGIS_full_version()"

sudo apt update
sudo apt install --only-upgrade -y postgresql-11 postgresql-11-postgis-2.5
</pre>
Вместо 11 и 2.5 укажите те версии, которе фактически установлены у вас.

=== Обновить расширение postgis до самой последней версии ===
Обязательно также обновить расширение в базе данных!
<pre>
sudo apt install -y postgresql-11-postgis-3

sudo -u postgres psql -d userside -A -t -c "ALTER EXTENSION postgis UPDATE"
sudo -u postgres psql -d userside -A -t -c "SELECT PostGIS_full_version()"
</pre>

=== Установить новую версию postgresql не удаляя старой ===
<pre>
sudo apt install -y postgresql-16 postgresql-16-postgis-3
</pre>

=== Сделать запасную резервную копию базы данных и настроек ===
Число 11 в имени файлов — это номер версии PostgreSQL, к которой относится эта резервная копия.
<pre>
sudo -u postgres pg_dump --no-acl -Fp -Z 5 userside --file=/backup/userside_emergency_11.sql.gz
sudo -u postgres pg_dump --no-acl -Fc userside --file=/backup/userside_emergency_11.dump
sudo tar czf /backup/postgres_config_emergency_11.tgz -C /etc/postgresql/11/main .
</pre>
Каталог /backup должен существовать и должен быть доступен для записи всем пользователям.

=== Удалить кластер БД, созданный автоматически сценарием при установке новой версии ===
При помощи утилиты <code>pg_lsclusters</code> из postgresql-common посмотрите, как выглядят ваши кластеры БД:
<pre>
sudo pg_lsclusters
</pre>
Вывод команды будет примерно следующим:
<pre>
Ver Cluster Port Status Owner Data directory Log file
11 main 5432 online postgres /var/lib/postgresql/11/main /var/log/postgresql/postgresql-11.log
16 main 5433 online postgres /var/lib/postgresql/16/main /var/log/postgresql/postgresql-16.log
</pre>
Кластер 16/main был создан автоматически сценарием установки postgresql. Его нужно остановить и удалить.
<pre>
sudo pg_dropcluster 16 main --stop
</pre>
Повторное выполнение команды <code>pg_lsclusters</code> должно показать, что у вас остался один кластер '''11/main'''.

=== Выполнить обновление кластера БД старой версии до кластера новой версии ===
Остановите службу postgresql
<pre>
sudo systemctl stop postgresql
</pre>
Запустите процесс обновления кластера БД '''11/main''' используя утилиту <code>pg_upgradecluster</code> из пакета postgresql-common. Это действие может занять много времени и дискового пространства.
<pre>
sudo pg_upgradecluster 11 main
</pre>
После завершения операции обновления вы увидите новое состояние кластеров (старая версия должна находиться в режиме '''down'''):
<pre>
Ver Cluster Port Status Owner Data directory Log file
11 main 5433 down postgres /var/lib/postgresql/11/main /var/log/postgresql/postgresql-11.log
16 main 5432 online postgres /var/lib/postgresql/16/main /var/log/postgresql/postgresql-16.log
</pre>
Запустите службу postgres
<pre>
sudo systemctl start postgresql
</pre>

=== Проверить работу USERSIDE ===
Сначала выполните команды, отображающие версии, чтобы убедиться что база данных теперь работает на кластере БД новой версии:
<pre>
sudo -u postgres psql -d userside -A -t -c "SELECT VERSION()"
sudo -u postgres psql -d userside -A -t -c "SELECT PostGIS_full_version()"
</pre>
Вы должны увидеть 16ю версию postgresql и 3.3.4 версию postgis. Может быть к тому времени, как вы будете читать эти строки, версия postgis будет более новой.

Теперь запустите службу FPM и зайдите в USERSIDE через браузер.
<pre>
sudo systemctl start php8.3-fpm
</pre>
Так как другие службы остановлены, вы, вероятно, увидите ошибки связанные с ними, но при этом интерфейс USERSIDE должен открыться без ошибок подключения к базе данных.
Если все успешно, то раскомментируйте закомментированные ранее строки в crontab и запустите внешние службы, находящиеся под управлением supervisor:
<pre>
sudo supervisorctl start all
sudo supervisorctl status
</pre>

=== Удалить кластер БД старой версии, устаревшие пакеты и запасные резервные копии ===
Если USERSIDE работает корректно, ошибок взаимодействия с БД нет, то можно удалить старый кластер и пакеты. Вы также, по желанию, можете удалить аварийные резервные копии или подождать несколько дней, чтобы точно убедиться, что они не пригодятся.
<pre>
sudo pg_dropcluster 11 main --stop
sudo apt purge -y postgresql-11 postgresql-11-postgis-2.5 postgresql-11-postgis-3
sudo apt autoremove -y
sudo rm /backup/userside_emergency_11* /backup/postgres_config_emergency_11.tgz
sudo rm -rf /var/lib/postgresql/11/main
</pre>

HOWTO: Обновление версии PostgreSQL

2025-04-13T17:46:52Z

Uscld2: /* Остановить USERSIDE */

[[HOWTO:_PostgreSQL_version_upgrade|en]] | [[HOWTO:_Обновление_версии_PostgreSQL|ru]]

В данном разделе описана процедура обновления PostgreSQL ''между основными версиями'' (например, с версии 11 на версию 16).

Обновление внутри версии (например, с версии 16.1 на версию 16.2) ''происходит автоматически и не требует дополнительных действий''.

'''Рекомендуем ознакомиться с официальными инструкциями по обновлению''' на сайте [https://www.postgresql.org/docs/current/upgrading.html postgresql.org].

В дистрибутиве Debian и основанных на нем существует пакет [https://packages.debian.org/sid/postgresql-common postgresql-common], устанавливаемый автоматически при установке пакета PostgreSQL. В состав postgresql-common входят инструменты, упрощающие работу с кластерами баз данных PostgreSQL. В том числе и обновление кластеров БД.

Кластером баз данных ([https://www.postgresql.org/docs/current/glossary.html Database cluster]) в PostgreSQL называется экземпляр сервера вместе со всеми обслуживаемыми БД, а не распределенную систему, как может показаться.

В следующем примере будет показано обновление кластера БД с версии 11 на версию 16 используя инструменты из пакета '''postgresql-common'''.

== Порядок обновления ==
# Остановить USERSIDE.
# Обновить текущую версии postgresql в пределах основной версии (например, с 11.5 до 11.22).
# Обновить расширение postgis до самой последней версии (например, с 2.5 до 3.3.4). Также обязательно обновить расширение и в самой базе данных.
# Установить новую версию postgresql не удаляя старой (например 16.1)
# Сделать запасную резервную копию базы данных и настроек
# Удалить кластер БД, созданный автоматически сценарием при установке новой версии
# Выполнить обновление кластера БД старой версии до кластера новой версии
# Проверить работу USERSIDE
# Удалить кластер БД старой версии, устаревшие пакеты и запасные резервные копии

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

[https://asciinema.org/a/do2AE0z30mg5JLIuI9zhGTPoR Посмотреть видеоинструкцию на asciinema].

== Пошаговая инструкция ==
SQL-запросы с оператором <code>SELECT</code>, приведенные далее, необходимы для определения текущих установленных версий в качестве справочной информации.

=== Остановить USERSIDE ===
<pre>
sudo supervisorctl stop all
sudo systemctl stop php8.3-fpm
</pre>
Версия php указана для примера. Используйте ту, что испльзуется у вас.

Закомментируйте запуск всех модулей и userside в crontab.

=== Обновить текущую версии postgresql в пределах основной версии ===
Проверить текущие версии. Обновить текущие пакеты PostgreSQL и PostGIS:
<pre>
sudo -u postgres psql -d userside -A -t -c "SELECT VERSION()"
sudo -u postgres psql -d userside -A -t -c "SELECT PostGIS_full_version()"

sudo apt update
sudo apt install --only-upgrade -y postgresql-11 postgresql-11-postgis-2.5
</pre>
Вместо 11 и 2.5 укажите те версии, которе фактически установлены у вас.

=== Обновить расширение postgis до самой последней версии ===
Обязательно также обновить расширение в базе данных!
<pre>
sudo apt install -y postgresql-11-postgis-3

sudo -u postgres psql -d userside -A -t -c "ALTER EXTENSION postgis UPDATE"
sudo -u postgres psql -d userside -A -t -c "SELECT PostGIS_full_version()"
</pre>

=== Установить новую версию postgresql не удаляя старой ===
<pre>
sudo apt install -y postgresql-16 postgresql-16-postgis-3
</pre>

=== Сделать запасную резервную копию базы данных и настроек ===
Число 11 в имени файлов — это номер версии PostgreSQL, к которой относится эта резервная копия.
<pre>
sudo -u postgres pg_dump --no-acl -Fp -Z 5 userside --file=/backup/userside_emergency_11.sql.gz
sudo -u postgres pg_dump --no-acl -Fc userside --file=/backup/userside_emergency_11.dump
sudo tar czf /backup/postgres_config_emergency_11.tgz -C /etc/postgresql/11/main .
</pre>
Каталог /backup должен существовать и должен быть доступен для записи всем пользователям.

=== Удалить кластер БД, созданный автоматически сценарием при установке новой версии ===
При помощи утилиты <code>pg_lsclusters</code> из postgresql-common посмотрите, как выглядят ваши кластеры БД:
<pre>
sudo pg_lsclusters
</pre>
Вывод команды будет примерно следующим:
<pre>
Ver Cluster Port Status Owner Data directory Log file
11 main 5432 online postgres /var/lib/postgresql/11/main /var/log/postgresql/postgresql-11.log
16 main 5433 online postgres /var/lib/postgresql/16/main /var/log/postgresql/postgresql-16.log
</pre>
Кластер 16/main был создан автоматически сценарием установки postgresql. Его нужно остановить и удалить.
<pre>
sudo pg_dropcluster 16 main --stop
</pre>
Повторное выполнение команды <code>pg_lsclusters</code> должно показать, что у вас остался один кластер '''11/main'''.

=== Выполнить обновление кластера БД старой версии до кластера новой версии ===
Остановите службу postgresql
<pre>
sudo systemctl stop postgresql
</pre>
Запустите процесс обновления кластера БД '''11/main''' используя утилиту <code>pg_upgradecluster</code> из пакета postgresql-common. Это действие может занять много времени и дискового пространства.
<pre>
sudo pg_upgradecluster 11 main
</pre>
После завершения операции обновления вы увидите новое состояние кластеров (старая версия должна находиться в режиме '''down'''):
<pre>
Ver Cluster Port Status Owner Data directory Log file
11 main 5433 down postgres /var/lib/postgresql/11/main /var/log/postgresql/postgresql-11.log
16 main 5432 online postgres /var/lib/postgresql/16/main /var/log/postgresql/postgresql-16.log
</pre>
Запустите службу postgres
<pre>
sudo systemctl start postgresql
</pre>

=== Проверить работу USERSIDE ===
Сначала выполните команды, отображающие версии, чтобы убедиться что база данных теперь работает на кластере БД новой версии:
<pre>
sudo -u postgres psql -d userside -A -t -c "SELECT VERSION()"
sudo -u postgres psql -d userside -A -t -c "SELECT PostGIS_full_version()"
</pre>
Вы должны увидеть 16ю версию postgresql и 3.3.4 версию postgis. Может быть к тому времени, как вы будете читать эти строки, версия postgis будет более новой.

Теперь запустите службу FPM и зайдите в USERSIDE через браузер.
<pre>
sudo systemctl start php8.1-fpm
</pre>
Так как другие службы остановлены, вы, вероятно, увидите ошибки связанные с ними, но при этом интерфейс USERSIDE должен открыться без ошибок подключения к базе данных.
Если все успешно, то раскомментируйте закомментированные ранее строки в crontab и запустите внешние службы, находящиеся под управлением supervisor:
<pre>
sudo supervisorctl start all
sudo supervisorctl status
</pre>

=== Удалить кластер БД старой версии, устаревшие пакеты и запасные резервные копии ===
Если USERSIDE работает корректно, ошибок взаимодействия с БД нет, то можно удалить старый кластер и пакеты. Вы также, по желанию, можете удалить аварийные резервные копии или подождать несколько дней, чтобы точно убедиться, что они не пригодятся.
<pre>
sudo pg_dropcluster 11 main --stop
sudo apt purge -y postgresql-11 postgresql-11-postgis-2.5 postgresql-11-postgis-3
sudo apt autoremove -y
sudo rm /backup/userside_emergency_11* /backup/postgres_config_emergency_11.tgz
sudo rm -rf /var/lib/postgresql/11/main
</pre>

ERP "USERSIDE"

2025-04-03T12:45:29Z

Uscld2:

[[ERP_"USERSIDE" EN|en]] | [[ERP_"USERSIDE"|ru]]

== Инструкция пользователя ==

актуальна для версии '''[[Версии ERP "USERSIDE"|3.19]]'''
* инструкции для предыдущих версий: [[ERP "USERSIDE" 3.18|3.18]], [[ERP "USERSIDE" 3.17|3.17]], [[ERP "USERSIDE" 3.16|3.16]], [[ERP "USERSIDE" 3.15|3.15]], [[ERP "USERSIDE" 3.14|3.14]], [[ERP "USERSIDE" 3.13|3.13]]

Официальный сайт: [https://userside.eu https://userside.eu]
* зеркало: [http://userside.ua https://userside.ua]

[https://www.youtube.com/channel/UCwocKxniJDc8cx0aWglpaFA YouTube-канал]

[https://t.me/usersideeu Telegram-группа]

== Основные данные ==

* [[О программе|Что такое UserSide? О программе]]
* [[Контактная информация]]
** [[Регламент технической поддержки]]
** [[Услуга по установке или обновлению ERP]]
** [[Приоритетное обслуживание]]
* [[Лицензионное соглашение]]
** [[Лимиты объектов]]
* [[Технические требования]]
* [[Установка|Установка USERSIDE на Linux-хост]]
* [[Docker окружение|Установка USERSIDE с использованием Docker окружения]]
* [[Настройка взаимодействия с биллингом]]
* [[Обновление|Обновление]]
* [[Установка#Резервное копирование|Резервное копирование, восстановление базы данных]]
* [[Демо-версия]]
* [[Версии ERP "USERSIDE"]]
* HOWTO
** [[Tuning|HOWTO: Тонкая настройка]]
** [[HOWTO: Обновление версии PostgreSQL]]
** [[HOWTO: Клонирование USERSIDE]]
* [[Частые вопросы]]

== Механика ==

* [[Start|С чего начать?]]
* [[Активность]]
* [[Адресная система]]
* [[Кабельные линии]]
* [[Коммутация объектов]]
** [[Общая схема коммутации]]
* [[Планирование]]
* [[Структурная схема]]
* [[PON]]
* [[Радио]]
* [[Видеонаблюдение|Видеонаблюдение/IP-камеры]]
* [[Внешний вид и индивидуальная настройка]]
* [[Языковая локализация]]
* [[Разграничение доступа|Разграничение доступа пользователей (операторов)]]
** [[Двухфакторная аутентификация (2FA)]]
** [[LDAP]]
* [[Поддерживаемые биллинги]]
** [[Универсальное API|Универсальное API для биллингов]]
** [[ABillS]]
** [[BGBilling]]
** [[Carbon Billing|Carbon Billing 5]]
** [[Hydra]]
** [[LANBilling]]
** [[MikBill]]
** [[NoDeny]]
** [[NoDenyPlus]]
** [[Platex]]
** [[uBilling]]
** [[UTM5]]
** [[Работа без биллинга]]
** [[Свой биллинг]]
** [[Одновременная работа с несколькими биллингами]]
* [[API]]
* [[QR-коды]]
* [["Горячие клавиши"]]

== Разделы системы ==

* Пользовательская часть
** [[Вход]]
** [[Главная страница]]
** [[Произвольные страницы и ссылки в меню]]
** Абоненты
*** [[Карточка абонента]]
**** [[Карточка юридического лица]]
**** [[Генерация документов]]
**** [[Функция PING]]
**** [[Дочерние записи]]
*** [[Добавление абонента]]
*** [[Список абонентов]]
*** [[Поиск]]
*** [[IP-сетка]]
**** [[Абоненты без IP-адресов]]
**** [[Абоненты без MAC-адресов]]
**** [[Зарезервированные IP-адреса]]
*** [[Должники]]
*** [[Активность в сети/интернете]]
*** [[Статус абонентов]]
*** [[График активности]]
*** [[График роста]]
*** [[TOP100 по трафику|TOP по трафику]]
*** [["Потерянные" абоненты]]
*** [[Абоненты на отключение]]
*** [[Отметки на абонентах]]
*** [[Бывшие абоненты]]
**** [[Карточка бывшего абонента]]
*** [[Неизвестные MAC-адреса]]
*** [[SMS-рассылка]]
*** [[Потенциальные абоненты]]
** Тарифы
*** [[Список тарифов]]
*** [[Группы тарифов]]
*** [[Трафик]]
*** [[Дополнительные услуги]]
** Сообщения
*** [[Переписка с абонентом]]
*** [[Входящие]]
*** [[Исходящие]]
*** [[Архив]]
*** [[Общесетевые]]
*** [[Список звонков]]
** Бухгалтерия
*** [[Остатки]]
*** [[Доход от абонплаты]]
*** [[Добросовестные]]
*** [[Сомнительные]]
*** [[Безнадежные]]
*** [[Заявки на смену тарифа]]
** Интерфейсы
** [[Сооружения связи]]
*** [[Карточка узла связи]]
**** [[Схема коммутации]]
**** [[Перепланировка коммутации]]
**** [[Стойки/шкафы]]
** Кабельная инфраструктура
*** [[Кабельные линии]]
**** [[Карточка линии]]
**** [[Маршруты линии на карте]]
**** [[Расчет маршрута соединений]]
**** [[Добавление линии с карты покрытия]]
**** [[Экспорт линии в KML]] ''(Google Earth)''
*** [[Кабельные каналы]]
*** [[Кроссы/ODF]]
*** [[Патч-панели]]
*** [[Розетки RJ-45]]
*** [[Делители/Уплотнители]]
*** [[Схемы коммутации]]
** [[Оборудование]]
*** Сателлиты: ''([[usm_satellite]])''
*** [[Уведомление персонала о неактивности оборудования]]
*** [[Системные устройства]]
**** [[Карточка системных устройств]]
*** [[Произвольные устройства]]
*** [[Коммутаторы]]
**** [[Карточка коммутатора]]
**** [[Автопривязка абонентов к портам]]
**** [[Коммутаторы - Отчеты|Отчеты]]
**** [[Горячая замена коммутатора]]
**** [[Интеграция ТМЦ в устройство]]
*** [[OLT]]
**** [[ONU]]
*** [[Радиооборудование]]
*** [[Медиаконвертеры]]
*** [[CWDM]]
*** [[VLAN]]
*** [[Структурная схема]]
** [[Журнал заданий]]
*** [[Группы и типы заданий на работу]]
*** [[План работ]]
*** [[Карточка задания]]
**** [[Чек-листы]]
**** [[Наряд на работу]]
***** [[Удаленное подтверждение нарядов]]
**** [[Уведомление персонала о заданиях]]
**** [[Настройка - Задания#Автоматическое назначение персонала|Автоматическое назначение персонала]]
**** [[Настройка - Задания#Цепочка заданий|Цепочка заданий]]
*** [[Мои задания]]
**** [[Наблюдение за заданиями]]
*** [[Новости]]
*** [[Периодические задания]]
*** [[Календарь]]
*** [[Почтовый робот|Почтовый робот - Создание задач по почте]]
** Склад
*** [[ТМЦ]]
**** [[Карточка ТМЦ]]
**** [[Интеграция ТМЦ в устройство]]
*** [[Операции]]
*** [[Склад - Отчеты|Отчеты]]
*** [[Поставщики]]
*** [[Каталог товаров]]
** Покрытие
*** [[Карты покрытия|Карты]]
*** [[Адреса]]
**** [[Карточка дома]]
**** [[Поэтажные планы зданий и сооружений]]
**** [[Логическая схема здания]]
**** [[Настройка структуры здания]]
*** [[Собственники]]
*** [[Ключи]]
*** [[Объекты на карте]]
** Персонал
*** [[Подразделения]]
*** [[Сотрудники]]
*** [[Табель работ]]
*** [[Ведомости работ]]
*** [[Учёт рабочего времени]]
*** [[Штрафы и премии]]
** [[Автотранспорт]]
** [[Рекламные кампании]]
** [[Блокнот]]
** [[Статистика]]
** Пользователи
*** [[Пользователи - Переписка|Переписка]]
*** [[Личная настройка]]
*** [[Учетные записи]]
*** [[Настройка профилей|Профили]]
*** [[История по пользователям|История]]
** Настройка
*** [[Настройка - Основная|Основная]]
**** [[ERP-профили]]
**** [[Проверка целостности файлов]]
**** [[Дополнительные метки для оборудования/линий]]
**** [[Импорт справочников]]
**** [[Настройка - Отметки на абонентах|Отметки на абонентах]]
**** [[Погода]]
**** [[Прикрепленные файлы]]
**** [[Уведомления|Уведомления (почта, sms)]]
**** [[Настройка - Праздничные интерфейсы|Праздничные интерфейсы]]
*** [[Адресная система|Адреса]]
*** [[Настройка - База оборудования|База оборудования]]
*** [[Настройка - Биллинги|Биллинги]]
*** [[Настройка - Документы|Документы]]
*** [[Настройка - Дополнительные услуги|Дополнительные услуги]]
*** [[Настройка - Кабельные линии|Кабельные линии]]
*** [[Настройка - Карты покрытия|Карты покрытия]]
*** [[Настройка - Задания|Задания]]
**** [[Настройка - Задания#Автоматическое назначение персонала|Автоматическое назначение персонала]]
**** [[Настройка - Задания#Цепочка заданий и автоматизации|Цепочка заданий и автоматизации]]
**** [[Настройка - Задания#Эскалация заданий|Эскалация заданий]]
*** [[Настройка - Модули|Модули]]
*** [[Настройка_-_Модуль_us_asterisk|Модуль usm_asterisk]]
*** [[Usm_observer|Модуль usm_observer]]
*** [[Настройка - Планировщик|Планировщик]]
**** 1. [[Выполнение SQL команды]]
**** 2. [[Планировщик - Автопривязка абонентов к портам|Автопривязка абонентов к портам]]
**** 3. [[Создание заданий для безнадежных абонентов]]
**** 4. [[Создание заданий для сомнительных абонентов]]
**** 5. [[Создание заданий для должников]]
**** 6. [[Создание заданий для группы абонентов]]
**** 22. [[Привязка абонентов к выполненным задачам]]
**** 23. [[Рассылка о заданиях на текущий день]]
**** 25. [[Получение версии прошивки коммутатора]]
**** 28. [[Планировщик - SMS-рассылка|SMS-рассылка]]
**** 30. [[Рассылка информации о снижении резервов на складе]]
**** 35. [[Создание заданий для неактивных абонентов]]
**** 38. [[Перенос неактивных абонентов в бывшие]]
**** 39. [[Получение информации по VLAN на устройствах]]
**** 40. [[Перенос информации о подключенных потенциальных клиентах в текущие]]
**** 41. [[Перенос неактивных абонентов в отключённые]]
**** 42. [[Добавление MAC-адресов для абонентов, что закреплены к портам коммутаторов из FDB-таблицы]]
**** 43. [[Перенос абонентов, которых нет в биллинге в бывшие абоненты]]
**** 44. [[E-mail уведомления авторам заданий о просроченных заданиях]]
**** 45. [[Перенос абонентов, которых нет в биллинге в отключенные абоненты]]
*** [[Настройка - Разделы/страницы/ссылки|Разделы/страницы/ссылки]]
*** [[Настройка - Список складов|Склады]]
*** [[Настройка - Сооружения связи|Сооружения связи]]

* [[Личный кабинет]]
** [[Регистрация]]
** [[Вход в личный кабинет|Вход]]
** [[Личный кабинет - Главная страница|Главная страница]]
** [[Тех.поддержка]]
** [[Личные данные]]
** [[История оплат и начислений]]
** [[Информация]]
** [[Произвольные ссылки и страницы в личном кабинете]]

* Скрипты
** [[Скрипт - Планировщик|Планировщик]]
** [[Заявка на подключение]]
** [[404 - обработка ненайденых страниц]]

== [[Модули]] ==

* [[usm_abills]]
* [[usm_asterisk]]
* [[usm_bgbilling]]
* '''[[usm_billing]]'''
* [[usm_cabletest]]
* [[usm_checker]]
* [[usm_gps_2|usm_gps]]
* [[usm_hydra]]
* [[usm_iferr]]
* [[usm_lanbilling]]
* [[usm_nodeny]]
* [[usm_nodeny_plus]]
* [[usm_observer]]
* [[usm_peleng]]
* [[usm_pon]]
* [[usm_radio]]
* [[usm_satellite]]
* [[usm_stat]]
* [[usm_utm5]]
* [[База оборудования]]
* [[Отключение копирайтов]]
* [[Написание своего модуля (API)]]
* [[python_venv|Виртуальная среда Python для модулей]]

== Взаимодействие с прочим ПО и сервисами ==

* [[SMS-операторы]]
** [[Написание собственного модуля для отправки SMS]]
* [[Jabber]]
* [[Binotel]]

Установка

2025-03-06T13:40:17Z

Uscld2: /* Восстановление из резервной копии */

<languages/>
[[Installation|en]] | [[Установка|ru]]

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

== Описание ==
В целях упрощения будут рассмотрены команды для операционной системы '''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 любой поддерживаемой на данный момент версии. Статус версий можно посмотреть здесь: "[https://devguide.python.org/versions/ 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 - <code>/var/www/userside</code>. Внутри этого каталога должен быть подкаталог 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. Вы можете копировать строки по одной и вставлять их в командную строку вашей операционной системы.

Следующие строки скопируйте и вставьте целиком:
<pre>
sudo tee /etc/apt/sources.list.d/contrib-non-free.list << EOL
deb http://deb.debian.org/debian/ $(lsb_release -sc) contrib non-free non-free-firmware
EOL

sudo apt update
sudo apt full-upgrade -y
sudo apt install -y gnupg ca-certificates lsb-release debian-archive-keyring debian-keyring libsnmp-dev snmp-mibs-downloader
</pre>

=== PostgreSQL ===
==== Альтернативный официальный репозиторий ====
Мы настоятельно рекомендуем использовать последнюю версию PostgreSQL, так как это всегда положительно сказывается на скорости работы. Добавьте в систему официальный репозиторий Postgres:
<pre>
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
</pre>
Если у вас другая операционная система, вы можете найти необходимые команды для нее на [https://www.postgresql.org/download/ официальном сайте 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
<pre>
sudo -u postgres createuser userside -P
sudo -u postgres createdb -e -E "UTF-8" -l "uk_UA.UTF-8" -O userside -T template0 userside
sudo -u postgres psql -d userside -c "CREATE EXTENSION postgis"
</pre>

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

=== 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):
<pre>
sudo systemctl restart redis
redis-cli -h 127.0.0.1 -p 6379 -a MYPASSWORDHERE ping
</pre>

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

==== Добавление альтернативных репозиториев ====
Следующий блок скопируйте и вставьте целиком в командную строку
<pre>
curl -1sLf https://dl.cloudsmith.io/public/rabbitmq/rabbitmq-erlang/gpg.E495BB49CC4BBE5B.key | sudo gpg --dearmor | sudo tee /usr/share/keyrings/rabbitmq-erlang-archive-keyring.gpg > /dev/null
curl -1sLf https://dl.cloudsmith.io/public/rabbitmq/rabbitmq-server/gpg.9F4587F226208342.key | sudo gpg --dearmor | sudo tee /usr/share/keyrings/rabbitmq-server-archive-keyring.gpg > /dev/null

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
</pre>

==== Установка ====
Убедитесь, что в /etc/hosts есть запись для имени вашего хоста. Отсутствие такрой записи (например, если вы изменили имя хоста после инсталляции) является основной ошибкой, возникающей при установке RabbitMQ. Так что лучше еще раз убедитесь, что запись соответствующая имени хосту имеется.
<pre>
sudo apt install -y erlang-base \
erlang-asn1 erlang-crypto erlang-eldap erlang-ftp erlang-inets \
erlang-mnesia erlang-os-mon erlang-parsetools erlang-public-key \
erlang-runtime-tools erlang-snmp erlang-ssl \
erlang-syntax-tools erlang-tftp erlang-tools erlang-xmerl

sudo apt install rabbitmq-server -y --fix-missing
</pre>

==== Установка необходимых дополнений ====
Следующие две строки выполняйте по одной за раз!
<pre>
sudo rabbitmq-plugins enable rabbitmq_management --offline

sudo rabbitmq-plugins enable rabbitmq_web_stomp --offline
</pre>

==== Настройка ====
Скопируйте и вставьте целиком следующий блок:
<pre>
sudo tee /etc/rabbitmq/rabbitmq.conf << EOF
listeners.tcp.default = 5672

web_stomp.port = 15674
web_stomp.cowboy_opts.max_keepalive = 60
EOF
</pre>

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

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

Создайте '''пользователя, от имени которого будут работать ERP USERSIDE''' и модули. Пример для имени пользователя '''userside''' (наделять админскими правами этого пользователя не нужно):
<pre>
sudo rabbitmqctl add_user "userside" "пароль_системы"
sudo rabbitmqctl set_user_tags "userside" "monitoring"
sudo rabbitmqctl set_permissions -p "/" "userside" ".*" ".*" ".*"
</pre>

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

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

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

Перезапустите службу rabbitmq:
<pre>
sudo systemctl restart rabbitmq-server
</pre>

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

По умолчанию WEB-интерфейс управления доступен по адресу http://userside.mycompany.com:15672. Рекомендуем использовать фаервол, чтобы ограничить доступ к этому интерфейсу управления.

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

=== PHP ===
==== Альтернативный репозиторий ====
<pre>
sudo curl -sSLo /usr/share/keyrings/deb.sury.org-php.gpg https://packages.sury.org/php/apt.gpg
sudo sh -c 'echo "deb [signed-by=/usr/share/keyrings/deb.sury.org-php.gpg] https://packages.sury.org/php/ $(lsb_release -sc) main" > /etc/apt/sources.list.d/php.list'
sudo apt update
</pre>

==== Установка ====
Выполните следующие команды:
<pre>
sudo apt install -y php8.3-{fpm,cli,common,curl,intl,mbstring,opcache,pgsql,readline,xml,zip,snmp,gd}
</pre>

Если вы планируете использовать LDAP, необходимо установить расширение php-ldap:
<pre>
sudo apt install -y php8.3-ldap
</pre>

Если вы планируете использовать отправку SMS используя TurboSMS, также понадобится расширение php-soap:
<pre>
sudo apt install -y php8.3-soap
</pre>

==== Настройка ====
Далее приведены команды, вносящие изменения в файлы конфигурации.
<pre>
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
</pre>

=== NGINX ===
==== Альтернативный официальный репозиторий ====
Версия NGINX, поставляемая в репозитории Debian, полностью подходит для использования и нет необходимости в добавлении альтернативного репозитория. Однако, если вам хочется всегда иметь последнюю версию, то выполните следующие строки, чтобы добавить в операционную систему официальный репозиторий nginx:
<pre>
curl https://nginx.org/keys/nginx_signing.key | gpg --dearmor \
| sudo tee /usr/share/keyrings/nginx-archive-keyring.gpg >/dev/null
echo "deb [signed-by=/usr/share/keyrings/nginx-archive-keyring.gpg] \
http://nginx.org/packages/debian `lsb_release -cs` nginx" \
| sudo tee /etc/apt/sources.list.d/nginx.list
echo -e "Package: *\nPin: origin nginx.org\nPin: release o=nginx\nPin-Priority: 900\n" \
| sudo tee /etc/apt/preferences.d/99nginx
sudo apt update
</pre>

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

==== Установка ====
<pre>
sudo apt install -y nginx
</pre>

==== Настройка ====
<pre>
sudo sed -i "s@^user.*;@user www-data www-data;@" "/etc/nginx/nginx.conf"
sudo systemctl restart nginx
</pre>

Следующий пример настройки подразумевает, что ERP USERSIDE будет установлен в стандартный каталог системы <code>/var/www/userside</code>. Если вы желаете установить ERP USERSIDE в другой каталог, пожалуйста, не забывайте исправлять его во всех последующих примерах. Чтобы не ошибиться, мы рекомендуем использовать именно каталог <code>/var/www/userside</code>.

Теперь отредактируйте файл /etc/nginx/conf.d/default.conf. Либо удалите его и создайте файл с именем /etc/nginx/conf.d/userside.conf. В любом случае, не зависимо от вашего выбора, содержимое файла должно быть следующим (вместо userside.mycompany.com укажите свое доменное имя):
<pre>
server {
listen 80 default_server;
server_name userside.mycompany.com;
charset utf-8;
client_max_body_size 100M;

access_log /var/log/nginx/userside-access.log;
error_log /var/log/nginx/userside-error.log;

root /var/www/userside/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; }
}
</pre>

Также, возможно, вы захотите настроить SSL и что-либо еще. Эта тема выходит за рамки данной инстуркции.

Если Вы установили RabbitMQ '''на другом сервере''', либо изменили значение порта WebSTOMP с 15674 на какой-то другой, то укажите IP-адрес сервера с RabbitMQ и номер порта в строке <code>proxy_pass http://127.0.0.1:15674/ws;</code>. Протокол должен оставаться http. Путь должен оставаться /ws.

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

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

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

==== Установка необходимых пакетов ====
sudo apt install -y python3-dev python3-pip python3-venv libffi-dev pkg-config

=== Supervisor ===
sudo apt install -y supervisor

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

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

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

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

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

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

Вы можете ввести любой доступный вам номер версии 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). Выполните команды:
<pre>
sudo cp etc/us-core-worker.conf-example /etc/supervisor/conf.d/us-core-worker.conf
sudo cp microservice/poller/etc/usm_poller.conf-example /etc/supervisor/conf.d/usm_poller.conf
sudo cp etc/logrotate-example /etc/logrotate.d/userside
sudo cp microservice/poller/etc/logrotate-example /etc/logrotate.d/usm_poller
sudo cp etc/crontab-example /etc/cron.d/userside
</pre>

=== Установка необходимых зависимостей для usm_poller ===
Создайте виртуальное окружение venv для python и установите зависимые модули, как показано далее:
<pre>
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
</pre>

=== Запуск супервизора ===
Супервизор контролирует работу служб, указанных в его конфигурации. Для запуска супервизора выполните:
<pre>
sudo systemctl restart supervisor
</pre>
После запуска супервизора, спустя несколько секунд можно понаблюдать за состоянием всех контролируемых им служб. Все службы должны быть в состоянии RUNNING:
<pre>
sudo supervisorctl status
</pre>

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

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

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

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

==== Процесс обновления ====
Мы настоятельно рекомендуем выполнять тестовые обновления на [[HOWTO:_Клонирование_USERSIDE|копии системы]].

Для проведения обновления запустите инсталлятор в режиме install и следуйте инструкциям:
<pre>
cd /var/www/userside
sudo -u www-data php userside_install.phar install
</pre>

После обновления USERSIDE нужно обязательно обновить зависимости usm_poller:
<pre>
cd /var/www/userside/microservice/poller
sudo -H venv/bin/pip install -U pip
sudo -H venv/bin/pip install -U -r requirements.txt
</pre>

Теперь нужно перезапустить все службы, которолируемые супервизором и проследить чтобы все они запустились и были в состоянии RUNNING:
<pre>
sudo supervisorctl restart all
sudo supervisorctl status
</pre>

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

=== Резервное копирование ===
Установите периодическое резервное копирование базы данных и пользовательских файлов. Желательно минимум раз в сутки в моменты наименьшей нагрузки на сервер. В PostgreSQL существует два способа создать резервную копию базы данных: dump и sql-script. У каждого из них есть свои преимущества и недостатки. Первый создает безопасный дамп базы данных целиком, а второй создает SQL-скрипт, выполняя который можно восстановить как структуру так и данные. Рекомендуем обратиться к [https://www.postgresql.org/docs/current/app-pgdump.html документации по использованию команды pg_dump] для выбора более подходящего для вас способа или набора параметров.

Ниже приведены две команды для создания резервной копии базы данных — выбирайте одну из них и добавляйте в ваш crontab:
<pre>
# 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
</pre>

Для создания минимальной резервной копии '''файлов''' можно использовать следующую команду (для версии 3.15 и новее):
sudo tar -czf /backup/userside.tgz .env common/config/settings.json var/attachments
Этих файлов вместе с базой данных будет достаточно для восстановления работы USERSIDE. Но вы можете выполнять резервное копирование всего каталога /var/www/userside для большей надежности.

=== Восстановление из резервной копии ===
Для восстановления из дампа используется команда pg_restore. [https://postgrespro.ru/docs/postgresql/13/app-pgrestore Документация по использованию pg_restore]. Для восстановления из SQL-скрипта используется утилита psql. [https://www.postgresql.org/docs/current/app-psql.html Документация по использованию psql].

Перед восстановлением базы данных из резервной копии нужно обязательно остановить работу USERSIDE.

1. Остановить cron userside и всех модулей
<pre>
mkdir -p ~/cron
sudo mv /etc/cron.d/userside ~/cron
sudo mv /etc/cron.d/userside-modules ~/cron
</pre>
2. Остановить работу фоновых служб
<pre>
sudo supervisorctl stop all
</pre>
3. Остановить работу php-fpm
<pre>
sudo systemctl stop php8.3-fpm
</pre>
Только после этого можно приступать к восстановлению базы данных из резервной копии.

==== SQL-script ====
Для восстановления БД из резервной копии в виде SQL-скрипта, сначала нужно пересоздать базу данных, а затем восстановить в пустую базу данных резервную копию:
<pre>
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
</pre>

==== DUMP ====
Дамп содержит целиком базу данных со всеми ее элементами. Поэтому перед восстановлением базы данных из дампа её не должно существовать на сервере — удалите базу данных перед восстановлением из дампа. Также важно, чтобы пользователь базы данных (владелец всех элементов) уже существовал — создайте его перед восстановлением, если вы восстанавливаете базу данных на новом сервере, где нужного пользователя еще нет.

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

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

==== После восстановления базы данных ====
После восстановления базы данных любым способом, необходимо очистить кэш ERP USERSIDE, т.к. в кэше теперь находятся данные, отличные от данных в базе. Перейтите в каталог /var/www/userside и выполните команду очистки кэша (первую, если используется пароль или вторую, если не используется):
<pre>
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
</pre>
Восстановите работу служб, которые были остановлены перед выполнением резервной копии:
<pre>
sudo mv ~/cron/* /etc/cron.d
sudo supervisorctl start all
sudo systemctl start php8.3-fpm
</pre>
Выполните команду восстановления, чтобы файлы системы соответствовали версии базы данных и проверить систему на целостность файлов.
<pre>
cd /var/www/userside
sudo -u www-data php userside_install.phar repair
</pre>

Установка

2025-03-06T13:39:12Z

Uscld2: /* Восстановление из резервной копии */

<languages/>
[[Installation|en]] | [[Установка|ru]]

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

== Описание ==
В целях упрощения будут рассмотрены команды для операционной системы '''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 любой поддерживаемой на данный момент версии. Статус версий можно посмотреть здесь: "[https://devguide.python.org/versions/ 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 - <code>/var/www/userside</code>. Внутри этого каталога должен быть подкаталог 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. Вы можете копировать строки по одной и вставлять их в командную строку вашей операционной системы.

Следующие строки скопируйте и вставьте целиком:
<pre>
sudo tee /etc/apt/sources.list.d/contrib-non-free.list << EOL
deb http://deb.debian.org/debian/ $(lsb_release -sc) contrib non-free non-free-firmware
EOL

sudo apt update
sudo apt full-upgrade -y
sudo apt install -y gnupg ca-certificates lsb-release debian-archive-keyring debian-keyring libsnmp-dev snmp-mibs-downloader
</pre>

=== PostgreSQL ===
==== Альтернативный официальный репозиторий ====
Мы настоятельно рекомендуем использовать последнюю версию PostgreSQL, так как это всегда положительно сказывается на скорости работы. Добавьте в систему официальный репозиторий Postgres:
<pre>
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
</pre>
Если у вас другая операционная система, вы можете найти необходимые команды для нее на [https://www.postgresql.org/download/ официальном сайте 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
<pre>
sudo -u postgres createuser userside -P
sudo -u postgres createdb -e -E "UTF-8" -l "uk_UA.UTF-8" -O userside -T template0 userside
sudo -u postgres psql -d userside -c "CREATE EXTENSION postgis"
</pre>

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

=== 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):
<pre>
sudo systemctl restart redis
redis-cli -h 127.0.0.1 -p 6379 -a MYPASSWORDHERE ping
</pre>

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

==== Добавление альтернативных репозиториев ====
Следующий блок скопируйте и вставьте целиком в командную строку
<pre>
curl -1sLf https://dl.cloudsmith.io/public/rabbitmq/rabbitmq-erlang/gpg.E495BB49CC4BBE5B.key | sudo gpg --dearmor | sudo tee /usr/share/keyrings/rabbitmq-erlang-archive-keyring.gpg > /dev/null
curl -1sLf https://dl.cloudsmith.io/public/rabbitmq/rabbitmq-server/gpg.9F4587F226208342.key | sudo gpg --dearmor | sudo tee /usr/share/keyrings/rabbitmq-server-archive-keyring.gpg > /dev/null

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
</pre>

==== Установка ====
Убедитесь, что в /etc/hosts есть запись для имени вашего хоста. Отсутствие такрой записи (например, если вы изменили имя хоста после инсталляции) является основной ошибкой, возникающей при установке RabbitMQ. Так что лучше еще раз убедитесь, что запись соответствующая имени хосту имеется.
<pre>
sudo apt install -y erlang-base \
erlang-asn1 erlang-crypto erlang-eldap erlang-ftp erlang-inets \
erlang-mnesia erlang-os-mon erlang-parsetools erlang-public-key \
erlang-runtime-tools erlang-snmp erlang-ssl \
erlang-syntax-tools erlang-tftp erlang-tools erlang-xmerl

sudo apt install rabbitmq-server -y --fix-missing
</pre>

==== Установка необходимых дополнений ====
Следующие две строки выполняйте по одной за раз!
<pre>
sudo rabbitmq-plugins enable rabbitmq_management --offline

sudo rabbitmq-plugins enable rabbitmq_web_stomp --offline
</pre>

==== Настройка ====
Скопируйте и вставьте целиком следующий блок:
<pre>
sudo tee /etc/rabbitmq/rabbitmq.conf << EOF
listeners.tcp.default = 5672

web_stomp.port = 15674
web_stomp.cowboy_opts.max_keepalive = 60
EOF
</pre>

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

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

Создайте '''пользователя, от имени которого будут работать ERP USERSIDE''' и модули. Пример для имени пользователя '''userside''' (наделять админскими правами этого пользователя не нужно):
<pre>
sudo rabbitmqctl add_user "userside" "пароль_системы"
sudo rabbitmqctl set_user_tags "userside" "monitoring"
sudo rabbitmqctl set_permissions -p "/" "userside" ".*" ".*" ".*"
</pre>

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

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

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

Перезапустите службу rabbitmq:
<pre>
sudo systemctl restart rabbitmq-server
</pre>

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

По умолчанию WEB-интерфейс управления доступен по адресу http://userside.mycompany.com:15672. Рекомендуем использовать фаервол, чтобы ограничить доступ к этому интерфейсу управления.

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

=== PHP ===
==== Альтернативный репозиторий ====
<pre>
sudo curl -sSLo /usr/share/keyrings/deb.sury.org-php.gpg https://packages.sury.org/php/apt.gpg
sudo sh -c 'echo "deb [signed-by=/usr/share/keyrings/deb.sury.org-php.gpg] https://packages.sury.org/php/ $(lsb_release -sc) main" > /etc/apt/sources.list.d/php.list'
sudo apt update
</pre>

==== Установка ====
Выполните следующие команды:
<pre>
sudo apt install -y php8.3-{fpm,cli,common,curl,intl,mbstring,opcache,pgsql,readline,xml,zip,snmp,gd}
</pre>

Если вы планируете использовать LDAP, необходимо установить расширение php-ldap:
<pre>
sudo apt install -y php8.3-ldap
</pre>

Если вы планируете использовать отправку SMS используя TurboSMS, также понадобится расширение php-soap:
<pre>
sudo apt install -y php8.3-soap
</pre>

==== Настройка ====
Далее приведены команды, вносящие изменения в файлы конфигурации.
<pre>
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
</pre>

=== NGINX ===
==== Альтернативный официальный репозиторий ====
Версия NGINX, поставляемая в репозитории Debian, полностью подходит для использования и нет необходимости в добавлении альтернативного репозитория. Однако, если вам хочется всегда иметь последнюю версию, то выполните следующие строки, чтобы добавить в операционную систему официальный репозиторий nginx:
<pre>
curl https://nginx.org/keys/nginx_signing.key | gpg --dearmor \
| sudo tee /usr/share/keyrings/nginx-archive-keyring.gpg >/dev/null
echo "deb [signed-by=/usr/share/keyrings/nginx-archive-keyring.gpg] \
http://nginx.org/packages/debian `lsb_release -cs` nginx" \
| sudo tee /etc/apt/sources.list.d/nginx.list
echo -e "Package: *\nPin: origin nginx.org\nPin: release o=nginx\nPin-Priority: 900\n" \
| sudo tee /etc/apt/preferences.d/99nginx
sudo apt update
</pre>

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

==== Установка ====
<pre>
sudo apt install -y nginx
</pre>

==== Настройка ====
<pre>
sudo sed -i "s@^user.*;@user www-data www-data;@" "/etc/nginx/nginx.conf"
sudo systemctl restart nginx
</pre>

Следующий пример настройки подразумевает, что ERP USERSIDE будет установлен в стандартный каталог системы <code>/var/www/userside</code>. Если вы желаете установить ERP USERSIDE в другой каталог, пожалуйста, не забывайте исправлять его во всех последующих примерах. Чтобы не ошибиться, мы рекомендуем использовать именно каталог <code>/var/www/userside</code>.

Теперь отредактируйте файл /etc/nginx/conf.d/default.conf. Либо удалите его и создайте файл с именем /etc/nginx/conf.d/userside.conf. В любом случае, не зависимо от вашего выбора, содержимое файла должно быть следующим (вместо userside.mycompany.com укажите свое доменное имя):
<pre>
server {
listen 80 default_server;
server_name userside.mycompany.com;
charset utf-8;
client_max_body_size 100M;

access_log /var/log/nginx/userside-access.log;
error_log /var/log/nginx/userside-error.log;

root /var/www/userside/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; }
}
</pre>

Также, возможно, вы захотите настроить SSL и что-либо еще. Эта тема выходит за рамки данной инстуркции.

Если Вы установили RabbitMQ '''на другом сервере''', либо изменили значение порта WebSTOMP с 15674 на какой-то другой, то укажите IP-адрес сервера с RabbitMQ и номер порта в строке <code>proxy_pass http://127.0.0.1:15674/ws;</code>. Протокол должен оставаться http. Путь должен оставаться /ws.

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

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

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

==== Установка необходимых пакетов ====
sudo apt install -y python3-dev python3-pip python3-venv libffi-dev pkg-config

=== Supervisor ===
sudo apt install -y supervisor

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

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

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

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

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

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

Вы можете ввести любой доступный вам номер версии 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). Выполните команды:
<pre>
sudo cp etc/us-core-worker.conf-example /etc/supervisor/conf.d/us-core-worker.conf
sudo cp microservice/poller/etc/usm_poller.conf-example /etc/supervisor/conf.d/usm_poller.conf
sudo cp etc/logrotate-example /etc/logrotate.d/userside
sudo cp microservice/poller/etc/logrotate-example /etc/logrotate.d/usm_poller
sudo cp etc/crontab-example /etc/cron.d/userside
</pre>

=== Установка необходимых зависимостей для usm_poller ===
Создайте виртуальное окружение venv для python и установите зависимые модули, как показано далее:
<pre>
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
</pre>

=== Запуск супервизора ===
Супервизор контролирует работу служб, указанных в его конфигурации. Для запуска супервизора выполните:
<pre>
sudo systemctl restart supervisor
</pre>
После запуска супервизора, спустя несколько секунд можно понаблюдать за состоянием всех контролируемых им служб. Все службы должны быть в состоянии RUNNING:
<pre>
sudo supervisorctl status
</pre>

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

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

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

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

==== Процесс обновления ====
Мы настоятельно рекомендуем выполнять тестовые обновления на [[HOWTO:_Клонирование_USERSIDE|копии системы]].

Для проведения обновления запустите инсталлятор в режиме install и следуйте инструкциям:
<pre>
cd /var/www/userside
sudo -u www-data php userside_install.phar install
</pre>

После обновления USERSIDE нужно обязательно обновить зависимости usm_poller:
<pre>
cd /var/www/userside/microservice/poller
sudo -H venv/bin/pip install -U pip
sudo -H venv/bin/pip install -U -r requirements.txt
</pre>

Теперь нужно перезапустить все службы, которолируемые супервизором и проследить чтобы все они запустились и были в состоянии RUNNING:
<pre>
sudo supervisorctl restart all
sudo supervisorctl status
</pre>

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

=== Резервное копирование ===
Установите периодическое резервное копирование базы данных и пользовательских файлов. Желательно минимум раз в сутки в моменты наименьшей нагрузки на сервер. В PostgreSQL существует два способа создать резервную копию базы данных: dump и sql-script. У каждого из них есть свои преимущества и недостатки. Первый создает безопасный дамп базы данных целиком, а второй создает SQL-скрипт, выполняя который можно восстановить как структуру так и данные. Рекомендуем обратиться к [https://www.postgresql.org/docs/current/app-pgdump.html документации по использованию команды pg_dump] для выбора более подходящего для вас способа или набора параметров.

Ниже приведены две команды для создания резервной копии базы данных — выбирайте одну из них и добавляйте в ваш crontab:
<pre>
# 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
</pre>

Для создания минимальной резервной копии '''файлов''' можно использовать следующую команду (для версии 3.15 и новее):
sudo tar -czf /backup/userside.tgz .env common/config/settings.json var/attachments
Этих файлов вместе с базой данных будет достаточно для восстановления работы USERSIDE. Но вы можете выполнять резервное копирование всего каталога /var/www/userside для большей надежности.

=== Восстановление из резервной копии ===
Для восстановления из дампа используется команда pg_restore. [https://postgrespro.ru/docs/postgresql/13/app-pgrestore Документация по использованию pg_restore]. Для восстановления из SQL-скрипта используется утилита psql. [https://www.postgresql.org/docs/current/app-psql.html Документация по использованию psql].

Перед восстановлением базы данных из резервной копии нужно обязательно остановить работу USERSIDE.
1. Остановить cron userside и всех модулей
<pre>
mkdir -p ~/cron
sudo mv /etc/cron.d/userside ~/cron
sudo mv /etc/cron.d/userside-modules ~/cron
</pre>
2. Остановить работу фоновых служб
<pre>
sudo supervisorctl stop all
</pre>
3. Остановить работу php-fpm
<pre>
sudo systemctl stop php8.3-fpm
</pre>
Только после этого можно приступать к восстановлению базы данных из резервной копии.

==== SQL-script ====
Для восстановления БД из резервной копии в виде SQL-скрипта, сначала нужно пересоздать базу данных, а затем восстановить в пустую базу данных резервную копию:
<pre>
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
</pre>

==== DUMP ====
Дамп содержит целиком базу данных со всеми ее элементами. Поэтому перед восстановлением базы данных из дампа её не должно существовать на сервере — удалите базу данных перед восстановлением из дампа. Также важно, чтобы пользователь базы данных (владелец всех элементов) уже существовал — создайте его перед восстановлением, если вы восстанавливаете базу данных на новом сервере, где нужного пользователя еще нет.

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

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

==== После восстановления базы данных ====
После восстановления базы данных любым способом, необходимо очистить кэш ERP USERSIDE, т.к. в кэше теперь находятся данные, отличные от данных в базе. Перейтите в каталог /var/www/userside и выполните команду очистки кэша (первую, если используется пароль или вторую, если не используется):
<pre>
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
</pre>
Восстановите работу служб, которые были остановлены перед выполнением резервной копии:
<pre>
sudo mv ~/cron/* /etc/cron.d
sudo supervisorctl start all
sudo systemctl start php8.3-fpm
</pre>
Выполните команду восстановления, чтобы файлы системы соответствовали версии базы данных и проверить систему на целостность файлов.
<pre>
cd /var/www/userside
sudo -u www-data php userside_install.phar repair
</pre>

Python-update

2025-02-07T13:09:12Z

Uscld2:

[[Python-update_EN|en]] | [[Python-update|ru]]

Если версия Python, установленная на вашей ОС, не поддерживается модулями или поллером, то необходимо установить дополнительно новую версию Python, удовлетворяющую всем требованиям.

Важно: Изменять системную версию Python на новую - не рекомендуется! Единственный правильный способ - это установить новую версию параллельно системной. Иначе могут перестать работать различные системные службы и утилиты, использующие Python.

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

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

После того, как все установлено, зайдите на сайт https://www.python.org/downloads/source/ и скопируйте номер последней версии текущей ветки или предыдущей, если текущая ветка слишком свежая. Например, если последняя версия 3.13.1, то надежней все таки установить версию 3.12.9, т.к. сразу после выхода новой версии (3.13) есть вероятность того, что не все зависимые пакеты ее поддерживают.

Далее вам нужно создать временную переменную окружения, значение которой будет содержать номер версии Python, которую вы собираетесь установить.

PY_VER=3.12.9

Далее приведены команды, которые вы просто выполняете по одной, одну за другой, чтобы контролировать процесс и в случае ошибки не выполнять остальные команды. Копируйте по одной строке и выполняйте:
curl -o python.tgz "https://www.python.org/ftp/python/${PY_VER}/Python-${PY_VER}.tgz"
tar xzf python.tgz
cd Python-${PY_VER}
./configure --enable-optimizations
make -j $(nproc)
sudo -H make altinstall
curl -sS https://bootstrap.pypa.io/get-pip.py | sudo -H python3.12
cd ..
sudo rm -rf Python-${PY_VER} python.tgz

После выполнения всех этих действий у вас в системе будет установлена дополнительно еще одна версия Python. В данном случае это Python 3.12 а также инструмент pip тоже с версией 3.12. Системная версия Python изменена не будет и мы не рекомендуем ее изменять, так как некоторые системные компоненты могут быть зависимы от нее.

Чтобы использовать именно эту версию python и pip, вам нужно указывать целиком имена файлов, которые вы запускаете. Например:
python3.12 --version
pip3.12 --version

Теперь, чтобы создать виртуальное окружение для какого-либо модуля либо поллера, вам нужно использовать следующий синтаксис:
sudo python3.12 -m venv venv
sudo venv/bin/pip install -U pip wheel
и т.д.

Usm observer

2025-02-01T08:37:48Z

Uscld2:

[[Usm_observer_EN|en]] | [[Usm_observer|ru]]

{{activ}}

'''usm_observer''' - это модуль для постоянного контроля средствами SNMP настраиваемых показателей у [[Оборудование|устройств]] и оповещения [[Сотрудники|сотрудников]] и [[Подразделения|подразделений]] о фактах выхода значений этих показателей за пределы установленных значений.

'''Данный модуль является заменой устаревшему модулю [[us_control]]'''

== Общие данные ==

'''Язык модуля:''' Python

'''Текущая версия:''' см. на странице: [[Модули]]

'''Статус модуля:''' [http://userside.ua/price.php Платный]

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

=== Установка ===

Скопируйте архив в каталог с модулями, например, /opt/userside и разархивируйте его.
<pre>
cd /opt/userside
sudo unzip usm_observer_2.0.0.zip
</pre>

Перейдите в каталог usm_observer, создайте виртуальное окружение
<pre>
cd usm_observer
sudo python3 -m venv venv
sudo venv/bin/pip install --upgrade pip
sudo venv/bin/pip install --upgrade -r requirements.txt
</pre>

=== Настройка ===

Если это первая настройка версии 2.х, то скопируйте пример конфигурационного файла
<pre>
sudo cp settings.yaml-example settings.yaml
</pre>

Отредактируйте файл settings.yaml. В разделе '''api''' укажите <code>url</code> вашего USERSIDE и [[UserSide API Key|API-ключ]] в поле <code>key</code>. В разделе '''log''' вы можете изменимть путь к логам в поле <code>path</code> и уровень логирования (DEBUG, INFO, WARNING, ERROR) в поле <code>level</code>. Если нужно чтобы лог выводился на стандартный вывод вместо файла, то для <code>path</code> укажите значение <code>STDOUT</code> — это может быть удобно при первоначальной настройке модуля.

== Тестовый запуск ==

Чтобы удобней контролировать первый тестовый запуск, установите в settings.yaml путь к логу в значение <code>STDOUT</code> и запустите модуль:
<pre>
venv/bin/python main.py
</pre>

Если модуль отработал корректно и корректно завершил работу, то установите корреткный путь к логу, чтиобы запись велась в файл.

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

== Автоматический запуск ==

Добавьте в crontab строку, предварительно изменив путь к модулю:
<pre>
2/* * * * * root /opt/userside/usm_observer/venv/bin/python /opt/userside/usm_observer/main.py
</pre>

Убедитесь, что модуль запускается. Для этого спустя несколько минут понаблюдайте за файлом журнала:
<pre>
tail -f /var/log/usm_observer/usm_observer.log
</pre>

== Ротация файлов журнала ==

Файлы журнала, создаваемые модулем, нуждаются в ротации. Для этого следует использовать стандартные инструменты ротации логов в операционной системе.

Следующая настройка будет выполнять ротацию всех файлов *.log ежесуточно и хранить 7 архивных копий (за 7 дней)

Создайте файл /etc/logrotate.d/usm_observer следующего содержания:
<pre>
/var/log/usm_observer/usm_observer.log {
rotate 7
daily
compress
delaycompress
missingok
notifempty
}
</pre>

== Логика работы ==

* Каждый запуск модуль проверяет состояние SNMP-параметров у контролируемых устройств. Если значение параметра выходит за пределы допустимого, то считается, что произошла тревога. Тревожных параметров на устройстве может быть несколько. По каждому устройству, где был найден тревожный параметр или наоборот - параметр пришёл в норму - формируется электронное письмо и/или SMS для выбранного ''(на уровне каждого устройства)'' круга получателей

* По каждому устройству формируется отдельное письмо/сообщение, в котором будут все параметры, состояние ''(тревога/норма)'' которых изменилось. В письме информация будет представлена развёрнуто, в SMS - компактно

* Следующее сообщение будет прислано только в случае, если изменился вновь какой-то параметр

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

* Для устройств, с которых удалось получить параметры - будет обновлена дата последней активности.

* Если указан ошибочный параметр ''(OID)'', то при опросе устройства - на этом параметре опрос данного устройства будет прекращен.

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

[[Файл:12-1.PNG|thumb|800px|center]]

== Общая настройка ==

[[Файл:12-2.PNG|thumb|800px|center]]

Для начала требуется указать список контролируемых параметров и события, при которых считать, что значения этих параметров вышли из нормы.

[[Файл:12-3.PNG|thumb|800px|center]]

Параметры можно компоновать в профили опроса

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

Ведётся лог опроса параметров ''(не все значения, а только их изменения)'', который хранится в базе системы

Имеется также и текущий список опрашиваемых устройств

== Настройка в карточке устройства ==

При редактировании карточки [[Оборудование|оборудования]] доступен блок, в котором можно выбрать профиль опроса для данного устройства, указать какие-то отдельные параметры для опроса, что не входят в выбранный профиль и указать получателей сообщений о тревоге

[[Файл:28.PNG|thumb|800px|center]]

В режиме просмотра блок модуля также выводится и из него есть возможность просмотреть текущее состояние параметров и лог изменения их состояния

[[Файл:25.PNG|thumb|800px|center]]

[[Файл:26.PNG|thumb|800px|center]]

[[Файл:27.PNG|thumb|800px|center]]

HOWTO: PostgreSQL version upgrade

2024-12-25T19:01:17Z

Uscld2: /* Step-by-step instructions */

[[HOWTO:_PostgreSQL_version_upgrade|en]] | [[HOWTO:_Обновление_версии_PostgreSQL|ru]]

This section describes how to upgrade PostgreSQL ''between major versions'' (e.g., from version 11 to version 16).

Upgrading within a version (e.g., from version 16.1 to version 16.2) ''is automatic and requires no additional steps.''

'''We recommend reading the official upgrade instructions''' at [https://www.postgresql.org/docs/current/upgrading.html postgresql.org].

In the Debian distribution and those based on it, there is a package [https://packages.debian.org/sid/postgresql-common postgresql-common] that is installed automatically when the PostgreSQL package is installed. Postgresql-common includes tools to simplify working with PostgreSQL database clusters. This includes updating database clusters.

A [https://www.postgresql.org/docs/current/glossary.html database cluster] in PostgreSQL is a server instance together with all the maintained databases, not a distributed system as it may seem.

The following example will show how to upgrade a database cluster from version 11 to version 16 using the tools in the '''postgresql-common''' package.

== Upgrade order ==
# Stop USERSIDE.
# Upgrade the current version of postgresql within the major version (e.g., from 11.5 to 11.22).
# Upgrade the postgis extension to the latest version (e.g. from 2.5 to 3.3.4). Also be sure to update the extension in the database itself.
# Install a new version of postgresql without uninstalling the old one (e.g. 16.1).
# Make a backup copy of the database and settings
# Delete the database cluster created automatically by the script when installing the new version
# Upgrade the database cluster of the old version to the cluster of the new version
# Check USERSIDE operation
# Remove the old version database cluster, obsolete packages and spare backups

Allocate time for this operation. It can take quite a long time depending on the size of the database and the performance of the server. Also, make sure you have the free space you will need to upgrade the cluster (at least as much as the current cluster, but more is better).

[https://asciinema.org/a/do2AE0z30mg5JLIuI9zhGTPoR View video tutorial on asciinema].

== Step-by-step instructions ==

=== Stop USERSIDE ===
<pre>
sudo supervisorctl stop all
sudo systemctl stop php8.1-fpm
</pre>
The php version is for example. Use the one you are using.

Comment out the startup of all modules and userside in crontab.

=== Upgrade the current version of postgresql within the major version ===
Check the current versions. Upgrade the current PostgreSQL and PostGIS packages:
<pre>
sudo -u postgres psql -d userside -A -t -c "SELECT VERSION()"
sudo -u postgres psql -d userside -A -t -c "SELECT PostGIS_full_version()"

sudo apt update
sudo apt install --only-upgrade -y postgresql-11 postgresql-11-postgis-2.5
</pre>
Instead of 11 and 2.5, specify the versions you actually have installed.

=== Upgrade the postgis extension to the latest version ===
Be sure to upgrade the extension in the database as well!
<pre>
sudo apt install -y postgresql-11-postgis-3

sudo -u postgres psql -d userside -A -t -c "ALTER EXTENSION postgis UPDATE"
sudo -u postgres psql -d userside -A -t -c "SELECT PostGIS_full_version()"
</pre>

=== Install a new version of postgresql without uninstalling the old one ===
<pre>
sudo apt install -y postgresql-16 postgresql-16-postgis-3
</pre>

=== Make a backup of the database and settings ===
The number 11 in the filename is the PostgreSQL version number to which this backup belongs.
<pre>
sudo -u postgres pg_dump --no-acl -Fp -Z 5 userside --file=/backup/userside_emergency_11.sql.gz
sudo -u postgres pg_dump --no-acl -Fc userside --file=/backup/userside_emergency_11.dump
sudo tar czf /backup/postgres_config_emergency_11.tgz -C /etc/postgresql/11/main .
</pre>
The /backup directory must exist and must be writable by all users.

=== Remove the database cluster created automatically by the script when installing a new version ===
Using the <code>pg_lsclusters</code> utility from postgresql-common, see what your database clusters look like:
<pre>
sudo pg_lsclusters
</pre>
The output of the command will be approximately as follows:
<pre>
Ver Cluster Port Status Owner Data directory Log file
11 main 5432 online postgres /var/lib/postgresql/11/main /var/log/postgresql/postgresql-11.log
16 main 5433 online postgres /var/lib/postgresql/16/main /var/log/postgresql/postgresql-16.log
</pre>
The 16/main cluster was created automatically by the postgresql installation script. It needs to be stopped and deleted.
<pre>
sudo pg_dropcluster 16 main --stop
</pre>
Running the <code>pg_lsclusters</code> command again should show that you have one '''11/main''' cluster left.

=== Perform an upgrade of the old version database cluster to the new version database cluster ===
Stop the postgresql service
<pre>
sudo systemctl stop postgresql
</pre>
Start the '''11/main''' database cluster upgrade process using the <code>pg_upgradecluster</code> utility from the postgresql-common package. This may take a lot of time and disc space.
<pre>
sudo pg_upgradecluster 11 main
</pre>
After the upgrade operation is complete, you will see the new state of the clusters (the old version should be in '''down''' mode):
<pre>
Ver Cluster Port Status Owner Data directory Log file
11 main 5433 down postgres /var/lib/postgresql/11/main /var/log/postgresql/postgresql-11.log
16 main 5432 online postgres /var/lib/postgresql/16/main /var/log/postgresql/postgresql-16.log
</pre>
Start the postgres service
<pre>
sudo systemctl start postgresql
</pre>

=== Verify the operation of USERSIDE ===
First run the commands displaying the versions to verify that the database is now running on the new version database cluster:
<pre>
sudo -u postgres psql -d userside -A -t -c "SELECT VERSION()"
sudo -u postgres psql -d userside -A -t -c "SELECT PostGIS_full_version()"
</pre>
You should see version 16 of postgresql and version 3.3.4 of postgis. Maybe by the time you read these lines, the postgis version will be newer.

Now start the FPM service and go to USERSIDE through your browser.
<pre>
sudo systemctl start php8.1-fpm
</pre>
Since the other services are stopped, you will probably see errors related to them, but the USERSIDE interface should open without database connection errors.
If everything is successful, then uncomment the previously commented lines in crontab and start the external services under supervisor control:
<pre>
sudo supervisorctl start all
sudo supervisorctl status
</pre>

=== Remove the old version database cluster, obsolete packages, and spare backups ===
If USERSIDE is running correctly, and there are no database communication errors, you can remove the old cluster and packages. You can also optionally delete the emergency backups or wait a few days to make sure they are not needed.
<pre>
sudo pg_dropcluster 11 main --stop
sudo apt purge -y postgresql-11 postgresql-11-postgis-2.5 postgresql-11-postgis-3
sudo apt autoremove -y
sudo rm /backup/userside_emergency_11* /backup/postgres_config_emergency_11.tgz
sudo rm -rf /var/lib/postgresql/11/main
</pre>

HOWTO: Обновление версии PostgreSQL

2024-12-25T19:01:02Z

Uscld2: /* Пошаговая инструкция */

[[HOWTO:_PostgreSQL_version_upgrade|en]] | [[HOWTO:_Обновление_версии_PostgreSQL|ru]]

В данном разделе описана процедура обновления PostgreSQL ''между основными версиями'' (например, с версии 11 на версию 16).

Обновление внутри версии (например, с версии 16.1 на версию 16.2) ''происходит автоматически и не требует дополнительных действий''.

'''Рекомендуем ознакомиться с официальными инструкциями по обновлению''' на сайте [https://www.postgresql.org/docs/current/upgrading.html postgresql.org].

В дистрибутиве Debian и основанных на нем существует пакет [https://packages.debian.org/sid/postgresql-common postgresql-common], устанавливаемый автоматически при установке пакета PostgreSQL. В состав postgresql-common входят инструменты, упрощающие работу с кластерами баз данных PostgreSQL. В том числе и обновление кластеров БД.

Кластером баз данных ([https://www.postgresql.org/docs/current/glossary.html Database cluster]) в PostgreSQL называется экземпляр сервера вместе со всеми обслуживаемыми БД, а не распределенную систему, как может показаться.

В следующем примере будет показано обновление кластера БД с версии 11 на версию 16 используя инструменты из пакета '''postgresql-common'''.

== Порядок обновления ==
# Остановить USERSIDE.
# Обновить текущую версии postgresql в пределах основной версии (например, с 11.5 до 11.22).
# Обновить расширение postgis до самой последней версии (например, с 2.5 до 3.3.4). Также обязательно обновить расширение и в самой базе данных.
# Установить новую версию postgresql не удаляя старой (например 16.1)
# Сделать запасную резервную копию базы данных и настроек
# Удалить кластер БД, созданный автоматически сценарием при установке новой версии
# Выполнить обновление кластера БД старой версии до кластера новой версии
# Проверить работу USERSIDE
# Удалить кластер БД старой версии, устаревшие пакеты и запасные резервные копии

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

[https://asciinema.org/a/do2AE0z30mg5JLIuI9zhGTPoR Посмотреть видеоинструкцию на asciinema].

== Пошаговая инструкция ==
SQL-запросы с оператором <code>SELECT</code>, приведенные далее, необходимы для определения текущих установленных версий в качестве справочной информации.

=== Остановить USERSIDE ===
<pre>
sudo supervisorctl stop all
sudo systemctl stop php8.1-fpm
</pre>
Версия php указана для примера. Используйте ту, что испльзуется у вас.

Закомментируйте запуск всех модулей и userside в crontab.

=== Обновить текущую версии postgresql в пределах основной версии ===
Проверить текущие версии. Обновить текущие пакеты PostgreSQL и PostGIS:
<pre>
sudo -u postgres psql -d userside -A -t -c "SELECT VERSION()"
sudo -u postgres psql -d userside -A -t -c "SELECT PostGIS_full_version()"

sudo apt update
sudo apt install --only-upgrade -y postgresql-11 postgresql-11-postgis-2.5
</pre>
Вместо 11 и 2.5 укажите те версии, которе фактически установлены у вас.

=== Обновить расширение postgis до самой последней версии ===
Обязательно также обновить расширение в базе данных!
<pre>
sudo apt install -y postgresql-11-postgis-3

sudo -u postgres psql -d userside -A -t -c "ALTER EXTENSION postgis UPDATE"
sudo -u postgres psql -d userside -A -t -c "SELECT PostGIS_full_version()"
</pre>

=== Установить новую версию postgresql не удаляя старой ===
<pre>
sudo apt install -y postgresql-16 postgresql-16-postgis-3
</pre>

=== Сделать запасную резервную копию базы данных и настроек ===
Число 11 в имени файлов — это номер версии PostgreSQL, к которой относится эта резервная копия.
<pre>
sudo -u postgres pg_dump --no-acl -Fp -Z 5 userside --file=/backup/userside_emergency_11.sql.gz
sudo -u postgres pg_dump --no-acl -Fc userside --file=/backup/userside_emergency_11.dump
sudo tar czf /backup/postgres_config_emergency_11.tgz -C /etc/postgresql/11/main .
</pre>
Каталог /backup должен существовать и должен быть доступен для записи всем пользователям.

=== Удалить кластер БД, созданный автоматически сценарием при установке новой версии ===
При помощи утилиты <code>pg_lsclusters</code> из postgresql-common посмотрите, как выглядят ваши кластеры БД:
<pre>
sudo pg_lsclusters
</pre>
Вывод команды будет примерно следующим:
<pre>
Ver Cluster Port Status Owner Data directory Log file
11 main 5432 online postgres /var/lib/postgresql/11/main /var/log/postgresql/postgresql-11.log
16 main 5433 online postgres /var/lib/postgresql/16/main /var/log/postgresql/postgresql-16.log
</pre>
Кластер 16/main был создан автоматически сценарием установки postgresql. Его нужно остановить и удалить.
<pre>
sudo pg_dropcluster 16 main --stop
</pre>
Повторное выполнение команды <code>pg_lsclusters</code> должно показать, что у вас остался один кластер '''11/main'''.

=== Выполнить обновление кластера БД старой версии до кластера новой версии ===
Остановите службу postgresql
<pre>
sudo systemctl stop postgresql
</pre>
Запустите процесс обновления кластера БД '''11/main''' используя утилиту <code>pg_upgradecluster</code> из пакета postgresql-common. Это действие может занять много времени и дискового пространства.
<pre>
sudo pg_upgradecluster 11 main
</pre>
После завершения операции обновления вы увидите новое состояние кластеров (старая версия должна находиться в режиме '''down'''):
<pre>
Ver Cluster Port Status Owner Data directory Log file
11 main 5433 down postgres /var/lib/postgresql/11/main /var/log/postgresql/postgresql-11.log
16 main 5432 online postgres /var/lib/postgresql/16/main /var/log/postgresql/postgresql-16.log
</pre>
Запустите службу postgres
<pre>
sudo systemctl start postgresql
</pre>

=== Проверить работу USERSIDE ===
Сначала выполните команды, отображающие версии, чтобы убедиться что база данных теперь работает на кластере БД новой версии:
<pre>
sudo -u postgres psql -d userside -A -t -c "SELECT VERSION()"
sudo -u postgres psql -d userside -A -t -c "SELECT PostGIS_full_version()"
</pre>
Вы должны увидеть 16ю версию postgresql и 3.3.4 версию postgis. Может быть к тому времени, как вы будете читать эти строки, версия postgis будет более новой.

Теперь запустите службу FPM и зайдите в USERSIDE через браузер.
<pre>
sudo systemctl start php8.1-fpm
</pre>
Так как другие службы остановлены, вы, вероятно, увидите ошибки связанные с ними, но при этом интерфейс USERSIDE должен открыться без ошибок подключения к базе данных.
Если все успешно, то раскомментируйте закомментированные ранее строки в crontab и запустите внешние службы, находящиеся под управлением supervisor:
<pre>
sudo supervisorctl start all
sudo supervisorctl status
</pre>

=== Удалить кластер БД старой версии, устаревшие пакеты и запасные резервные копии ===
Если USERSIDE работает корректно, ошибок взаимодействия с БД нет, то можно удалить старый кластер и пакеты. Вы также, по желанию, можете удалить аварийные резервные копии или подождать несколько дней, чтобы точно убедиться, что они не пригодятся.
<pre>
sudo pg_dropcluster 11 main --stop
sudo apt purge -y postgresql-11 postgresql-11-postgis-2.5 postgresql-11-postgis-3
sudo apt autoremove -y
sudo rm /backup/userside_emergency_11* /backup/postgres_config_emergency_11.tgz
sudo rm -rf /var/lib/postgresql/11/main
</pre>

Python-update EN

2024-12-13T09:00:59Z

Uscld2:

[[Python-update_EN|en]] | [[Python-update|ru]]

If the version of Python installed on your OS is not supported by modules or poller, you must install an additional new version of Python that meets all requirements.

Important: Changing the system version of Python to the new version is not recommended! The only correct way is to install the new version in parallel with the system version. Otherwise, various system services and utilities that use Python may stop working.

First make sure you have all the necessary global packages installed in Python, which are needed globally to run the virtual environment, to build other dependencies.

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

Once everything is installed, go to https://www.python.org/downloads/source/ and copy the latest version number of the current branch, or the previous version if the current branch is too recent. For example, if the latest version is 3.13.1, it is more reliable to install version 3.12.8, because as soon as a new version (3.13) is released, there is a chance that not all dependent packages support it.

Next, you need to create a temporary environment variable whose value will contain the version number of the Python version you are going to install.

PY_VER=3.12.8

The following are commands that you simply execute one at a time, one after the other, to control the process and in case of error not to execute the rest of the commands. Copy one line at a time and execute:
curl -o python.tgz "https://www.python.org/ftp/python/${PY_VER}/Python-${PY_VER}.tgz"
tar xzf python.tgz
cd Python-${PY_VER}
./configure --enable-optimizations
make -j $(nproc)
sudo -H make altinstall
curl -sS https://bootstrap.pypa.io/get-pip.py | sudo -H python3.12
cd ..
sudo rm -rf Python-${PY_VER} python.tgz

After performing all these steps, you will have another version of Python installed on your system. In this case it is Python 3.12 and the pip tool is also version 3.12. The system version of Python will not be changed and we do not recommend changing it, as some system components may be dependent on it.

To use this particular version of python and pip, you need to specify the entire names of the files you run. For example:
python3.12 --version
pip3.12 --version

Now, to create a virtual environment for any module or poller, you need to use the following syntax:
sudo python3.12 -m venv venv
sudo venv/bin/pip install -U pip wheel
and so on.

Python-update

2024-12-13T09:00:17Z

Uscld2:

[[Python-update_EN|en]] | [[Python-update|ru]]

Если версия Python, установленная на вашей ОС, не поддерживается модулями или поллером, то необходимо установить дополнительно новую версию Python, удовлетворяющую всем требованиям.

Важно: Изменять системную версию Python на новую - не рекомендуется! Единственный правильный способ - это установить новую версию параллельно системной. Иначе могут перестать работать различные системные службы и утилиты, использующие Python.

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

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

После того, как все установлено, зайдите на сайт https://www.python.org/downloads/source/ и скопируйте номер последней версии текущей ветки или предыдущей, если текущая ветка слишком свежая. Например, если последняя версия 3.13.1, то надежней все таки установить версию 3.12.8, т.к. сразу после выхода новой версии (3.13) есть вероятность того, что не все зависимые пакеты ее поддерживают.

Далее вам нужно создать временную переменную окружения, значение которой будет содержать номер версии Python, которую вы собираетесь установить.

PY_VER=3.12.8

Далее приведены команды, которые вы просто выполняете по одной, одну за другой, чтобы контролировать процесс и в случае ошибки не выполнять остальные команды. Копируйте по одной строке и выполняйте:
curl -o python.tgz "https://www.python.org/ftp/python/${PY_VER}/Python-${PY_VER}.tgz"
tar xzf python.tgz
cd Python-${PY_VER}
./configure --enable-optimizations
make -j $(nproc)
sudo -H make altinstall
curl -sS https://bootstrap.pypa.io/get-pip.py | sudo -H python3.12
cd ..
sudo rm -rf Python-${PY_VER} python.tgz

После выполнения всех этих действий у вас в системе будет установлена дополнительно еще одна версия Python. В данном случае это Python 3.12 а также инструмент pip тоже с версией 3.12. Системная версия Python изменена не будет и мы не рекомендуем ее изменять, так как некоторые системные компоненты могут быть зависимы от нее.

Чтобы использовать именно эту версию python и pip, вам нужно указывать целиком имена файлов, которые вы запускаете. Например:
python3.12 --version
pip3.12 --version

Теперь, чтобы создать виртуальное окружение для какого-либо модуля либо поллера, вам нужно использовать следующий синтаксис:
sudo python3.12 -m venv venv
sudo venv/bin/pip install -U pip wheel
и т.д.

Usm cabletest EN

2024-10-28T11:24:41Z

Uscld2: /* Installing and configuring the module */

[[Usm_cabletest_EN|en]] | [[Usm_cabletest|ru]]

'''USM_CABLETEST''' ''- it is a module for periodic polling by cable tester of cable lengths for known switch models, fixing the results and outputting notifications about the change of values''

'''Module Language:''' Perl

'''Current version:''' see page: [[Modules_EN|Modules]]

'''Module Status:''' [https://www.userside.eu/en/pricing Paid]

Required Perl modules:
Time::Local
Socket
FindBin
URI
URI::Escape
LWP::UserAgent
JSON
Data::Dumper
Net::Telnet
Net::SNMP

For general information for all modules, see the page: [[Modules_EN|Modules]]

== Supported device models ==
D-Link DES-3010G
D-Link DES-3026
D-Link DES-3028
D-Link DES-3028G
D-Link DES-3052
D-Link DES-3200-10
D-Link DES-3200-10/C1
D-Link DES-3200-18
D-Link DES-3200-18/C1
D-Link DES-3200-26
D-Link DES-3200-26/C1
D-Link DES-3200-28
D-Link DES-3200-28/C1
D-Link DES-3200-28F
D-Link DES-3200-28F/C1
D-Link DES-3200-52
D-Link DES-3200-52/C1
D-Link DES-3526
D-Link DES-3528
D-Link DGS-3000-24TC
D-Link DGS-3120-24SC
D-Link DGS-3120-24TC
D-Link DGS-3200-10
D-Link DGS-3200-16

To add support for other switch models ''(that have cable tester)'' - contact us.

== Main features ==

* periodically obtaining information about the length of cables included in the copper ports of switches or about the absence of cables at all
* recording of the obtained results
* control of the facts of cable length changes and output of corresponding notifications

The method of data acquisition - '''telnet''' or '''SNMP''' (depending on the switch model).

In one run, the module connects to one device and attempts to poll it.

== Installing and configuring the module ==

# Allocate a separate catalogue. A completely arbitrary one. It is better not to place it in a catalogue accessible via web. Interaction with ERP "UserSide" is carried out through API means via http/s-protocol. In this way the module is fully autonomous and can work on any separate computer in any subnet. Also create a separate directory for the module logs. Do not forget to grant write permissions to it.
# Transfer there the files from the module archive. Rename the sample configuration file "usm_cabletest.conf-example" to "usm_cabletest.conf". In it, configure the parameters. The list of possible parameters is listed below.
# Check for additional perl-packages that are required to run the module. Their list is given above. If you do not have them installed, the module will generate an error at startup and the perl-package will need to be installed ''(using CPAN or PPM)''.
# Enable usm_cabletest module in the "[[Settings - Modules]]" section.
# Run the module manually

perl usm_cabletest.pl

It should start and run without errors.

7. Write the module startup into the system cron, according to the recommendations below

'''Clarifications:'''
* The module processes only one device at startup. Therefore, the system cron should be set to call the required number of copies of the module ''(based on the number of switches of suitable models in the system and the desired polling frequency)''.
* The module processes one device at startup. Therefore, the module can process 15 devices in 15 minutes. Any number of copies of the module can be started. To ensure that the simultaneous launch of a large number of copies of the module does not lead to increased load on the switches and the server ''(because the same tasks will be performed during the launch)'' the parameter "$delay" is used. By specifying in it a number of arbitrary delay, for example in "20" - you can achieve that the modules will be started from 1 to 20 seconds in random order and the load will be distributed.

'''IMPORTANT:''' Note that the cable tester polling is an internal diagnostic operation of the switch. It is possible that the switch will switch the port on/off to obtain correct data. It is also possible that frequent polling may cause the equipment to freeze.

It is also necessary to take into account that the cable tester data may be inaccurate. The error can reach several metres.

Example from the cron of launching five copies of the module:
* * * * * root perl /home/usm_cabletest/usm_cabletest.pl > /dev/null
* * * * * root perl /home/usm_cabletest/usm_cabletest.pl > /dev/null
* * * * * root perl /home/usm_cabletest/usm_cabletest.pl > /dev/null
* * * * * root perl /home/usm_cabletest/usm_cabletest.pl > /dev/null
* * * * * root perl /home/usm_cabletest/usm_cabletest.pl > /dev/null

In the card of the device polled by the usm_cabletest module you can view the history of polling of this device by the module and the general table of device polling by clicking the corresponding link. Also in the table of ports in the card of this device you can see the last known cable lengths on the polled ports.

== Parameters ==

The module is configured in the '''usm_cabletest.conf''' file.

$usUrl - URL to ERP "UserSide"
$usApiKey - [[API]]-key to ERP "UserSide"
$logsPath - Path to the catalogue for module logs

$isSilence - Flag - hide notifications to the console when the module is running
$delay - Custom time delay from 0 to n-seconds after module start. Allows you to reduce the load on the server when using a large number of modules at the same time

The usm_cabletest module can be run with the ''(specify a specific device to poll)'' parameter

Example:

perl usm_cabletest 998

will poll the switch with ID 998

== Operation information ==

On the "Settings - Modules - usm_cabletest" page you can view the report of polling by the equipment module by clicking on the link
***

Separately, you can view the data for this device in the equipment card
***

The latest data is displayed in the ports table
***

In the home page setting - the user can enable the output of cable length change information to the home page
***

***

== If the information is not captured/module does not work ==

1. It is necessary to distinguish and understand whether the module is not working or information is not captured. On the "Settings - Modules - usm_cabletest - Module Run Information" page, you should check the usm_cabletest module run logs and results.

2. You should make sure that the community access, passwords are correct and the device itself is physically connected and working.

3. In the ERP "UserSide" itself, open the switch card and click on the "Cable tester" link

4. For the test - you should run the module specifically for a particular switch. For example:

perl usm_cabletest.pl 998

will start the module for switch ID: 998

Check if there are no errors in the information output.

In the log files, analyse the information received.

Usm cabletest

2024-10-28T11:24:16Z

Uscld2: /* Установка и настройка модуля */

[[Usm_cabletest_EN|en]] | [[Usm_cabletest|ru]]

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

'''Язык модуля:''' Perl

'''Текущая версия:''' см. на странице: [[Модули]]

'''Статус модуля:''' [http://userside.eu/price.php Платный]

Необходимые модули Perl:
Time::Local
Socket
FindBin
URI
URI::Escape
LWP::UserAgent
JSON
Data::Dumper
Net::Telnet
Net::SNMP

Общую информацию для всех модулей см. на странице: [[Модули]]

== Поддерживаемые модели устройств ==

D-Link DES-3010G
D-Link DES-3026
D-Link DES-3028
D-Link DES-3028G
D-Link DES-3052
D-Link DES-3200-10
D-Link DES-3200-10/C1
D-Link DES-3200-18
D-Link DES-3200-18/C1
D-Link DES-3200-26
D-Link DES-3200-26/C1
D-Link DES-3200-28
D-Link DES-3200-28/C1
D-Link DES-3200-28F
D-Link DES-3200-28F/C1
D-Link DES-3200-52
D-Link DES-3200-52/C1
D-Link DES-3526
D-Link DES-3528
D-Link DGS-3000-24TC
D-Link DGS-3120-24SC
D-Link DGS-3120-24TC
D-Link DGS-3200-10
D-Link DGS-3200-16

Для добавления поддержки иных моделей коммутаторов ''(в которых есть кабельный тестер)'' - свяжитесь с нами.

== Основные функции ==

* периодическое получение информации о длине кабелей, включённых в медные порты коммутаторов либо об отсутствии там кабеля вовсе
* фиксация полученных результатов
* контроль фактов изменения длин кабелей и вывод соответствующих уведомлений

Метод получения данных - '''telnet''' или '''SNMP''' (в зависимости от модели коммутатора).

За один запуск модуль подключается к одному устройству и пытается выполнить для него опрос.

== Установка и настройка модуля ==

# Выделите отдельный каталог. Абсолютно произвольный. Лучше его не размещать в каталоге, доступном через web. Взаимодействие с ERP "UserSide" осуществляется средствами API по http/s-протоколу. Таким образом модуль полностью автономен и может работать на любом отдельном компьютере в любой подсети. Также создайте отдельный каталог для логов модуля. Не забудьте указать для него права на запись.
# Перенесите туда файлы из архива модуля. Пример файла конфигурации "usm_cabletest.conf-example" переименуйте в "usm_cabletest.conf". В нём выполните настройку параметров. Перечень возможных параметров указан ниже.
# Проверьте наличие дополнительных perl-пакетов, которые требуются для запуска модуля. Их список приведён выше. Если у вас они не установлены - модуль выдаст ошибку при запуске и perl-пакет необходимо будет установить ''(с помощью CPAN или PPM)''.
# В разделе "[[Настройка - Модули]]" включите работу с модулем usm_cabletest
# Запустите модуль вручную

perl usm_cabletest.pl

Он должен запуститься и отработать без ошибок.

7. Впишите запуск модуля в системный cron, согласно рекомендациям ниже

'''Уточнения:'''
* При запуске модуль обрабатывает только одно устройство. Следовательно в системный cron следует записать вызов необходимого количества копий модуля ''(из расчёта количества коммутаторов подходящих моделей в системе и желаемой частоты опроса)''.
* Модуль при запуске обрабатывает одно устройство. Следовательно за 15 минут модуль успеет обработать 15 устройств. Копий модуля можно запускать любое количество. Для того чтобы одновременный запуск большого количества копий модуля не приводил к увеличенной нагрузке на сами коммутаторы и сервер ''(ведь при запуске будут выполняться одни и те же однотипные задачи)'' предназначен параметр "$delay". Указав в нём цифру произвольное задержки например в "20" - можно добиться что модули будут запускаться с 1 по 20 секунду в произвольном порядке и нагрузка распределится.

'''ВАЖНО:''' Следует иметь в виду, что опрос кабельным тестером - это внутренняя диагностическая операция коммутатора. Не исключено, что коммутатор будет включать/выключать порт для получения корректных данных. Также не исключено, что частые опросы могут приводить к зависанию оборудования.

Еще требуется взять во внимание, что данные кабельного тестера могут быть неточны. Погрешность может достигать нескольких метров.

Пример из cron запуска пяти копий модуля:
* * * * * root perl /home/usm_cabletest/usm_cabletest.pl > /dev/null
* * * * * root perl /home/usm_cabletest/usm_cabletest.pl > /dev/null
* * * * * root perl /home/usm_cabletest/usm_cabletest.pl > /dev/null
* * * * * root perl /home/usm_cabletest/usm_cabletest.pl > /dev/null
* * * * * root perl /home/usm_cabletest/usm_cabletest.pl > /dev/null

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

== Параметры ==

Настройка модуля осуществляется в файле '''usm_cabletest.conf'''

$usUrl - URL к ERP "UserSide"
$usApiKey - [[API]]-ключ к ERP "UserSide"
$logsPath - Путь к каталогу для логов модуля

$isSilence - Флаг - скрывать уведомления в консоль при работе модуля
$delay - Произвольная временная задержка от 0 до n-секунд после запуска модуля. Позволяет уменьшить нагрузку на сервер при одновременном использовании большого количества модулей

Модуль usm_cabletest можно запускать с параметром ''(указать конкретное устройство, которое необходимо опросить)''

Пример:

perl usm_cabletest 998

опросит коммутатор с ID 998

== Информация о работе ==

На странице "Настройка - Модули - usm_cabletest" можно по ссылке просмотреть отчёт об опросах модулем оборудования
[[Файл:Ct03.png|thumb|800px|center]]

Отдельно в карточке оборудования можно посмотреть данные по этому устройству
[[Файл:Ct02.png|thumb|800px|center]]

Последние данные выводятся в таблице портов
[[Файл:Ct04.png|thumb|800px|center]]

В настройке главной страницы - пользователь может включить вывод информации об изменении длины кабеля на главную страницу
[[Файл:Ct01.png|thumb|800px|center]]

[[Файл:Ct05.png|thumb|800px|center]]

== Если информация не снимается/модуль не работает ==

1. Необходимо разграничить и понять - не работает модуль или не снимается информация. На странице "Настройка - Модули - usm_cabletest - Информация о работе модуля" следует проверить логи запусков модуля usm_cabletest и результаты.

2. Следует убедиться, что верны community доступа, пароли и само устройство физически подключено и работает.

3. В самой ERP "UserSide" откройте карточку коммутатора и перейдите по ссылке "Кабельный тестер"

4. Для теста - следует запустить модуль конкретно для определенного коммутатора. Например:

perl usm_cabletest.pl 998

запустит модуль для коммутатора ID: 998

Проверяем нет ли ошибок в выводе информации.

В файлах логов анализируем полученную информацию.

Usm cabletest EN

2024-10-28T11:23:32Z

Uscld2: /* Installing and configuring the module */

[[Usm_cabletest_EN|en]] | [[Usm_cabletest|ru]]

'''USM_CABLETEST''' ''- it is a module for periodic polling by cable tester of cable lengths for known switch models, fixing the results and outputting notifications about the change of values''

'''Module Language:''' Perl

'''Current version:''' see page: [[Modules_EN|Modules]]

'''Module Status:''' [https://www.userside.eu/en/pricing Paid]

Required Perl modules:
Time::Local
Socket
FindBin
URI
URI::Escape
LWP::UserAgent
JSON
Data::Dumper
Net::Telnet
Net::SNMP

For general information for all modules, see the page: [[Modules_EN|Modules]]

== Supported device models ==
D-Link DES-3010G
D-Link DES-3026
D-Link DES-3028
D-Link DES-3028G
D-Link DES-3052
D-Link DES-3200-10
D-Link DES-3200-10/C1
D-Link DES-3200-18
D-Link DES-3200-18/C1
D-Link DES-3200-26
D-Link DES-3200-26/C1
D-Link DES-3200-28
D-Link DES-3200-28/C1
D-Link DES-3200-28F
D-Link DES-3200-28F/C1
D-Link DES-3200-52
D-Link DES-3200-52/C1
D-Link DES-3526
D-Link DES-3528
D-Link DGS-3000-24TC
D-Link DGS-3120-24SC
D-Link DGS-3120-24TC
D-Link DGS-3200-10
D-Link DGS-3200-16

To add support for other switch models ''(that have cable tester)'' - contact us.

== Main features ==

* periodically obtaining information about the length of cables included in the copper ports of switches or about the absence of cables at all
* recording of the obtained results
* control of the facts of cable length changes and output of corresponding notifications

The method of data acquisition - '''telnet''' or '''SNMP''' (depending on the switch model).

In one run, the module connects to one device and attempts to poll it.

== Installing and configuring the module ==

# Allocate a separate catalogue. A completely arbitrary one. It is better not to place it in a catalogue accessible via web. Interaction with ERP "UserSide" is carried out through API means via http/s-protocol. In this way the module is fully autonomous and can work on any separate computer in any subnet. Also create a separate directory for the module logs. Do not forget to grant write permissions to it.
# Transfer there the files from the module archive. Rename the sample configuration file "usm_cabletest.conf-example" to "usm_cabletest.conf". In it, configure the parameters. The list of possible parameters is listed below.
# Check for additional perl-packages that are required to run the module. Their list is given above. If you do not have them installed, the module will generate an error at startup and the perl-package will need to be installed ''(using CPAN or PPM)''.
# Enable usm_cabletest module in the "[[Settings - Modules]]" section.
# Run the module manually

perl usm_cabletest.pl

It should start and run without errors.

7. Write the module startup into the system cron, according to the recommendations below

'''Clarifications:'''
* The module processes only one device at startup. Therefore, the system cron should be set to call the required number of copies of the module ''(based on the number of switches of suitable models in the system and the desired polling frequency)''.
* The module processes one device at startup. Therefore, the module can process 15 devices in 15 minutes. Any number of copies of the module can be started. To ensure that the simultaneous launch of a large number of copies of the module does not lead to increased load on the switches and the server ''(because the same tasks will be performed during the launch)'' the parameter "$delay" is used. By specifying in it a number of arbitrary delay, for example in "20" - you can achieve that the modules will be started from 1 to 20 seconds in random order and the load will be distributed.

'''IMPORTANT:''' Note that the cable tester polling is an internal diagnostic operation of the switch. It is possible that the switch will switch the port on/off to obtain correct data. It is also possible that frequent polling may cause the equipment to freeze.

It is also necessary to take into account that the cable tester data may be inaccurate. The error can reach several metres.

Example from the cron of launching five copies of the module:
* * * * * root perl /home/usm_cabletest/usm_cabletest.pl &> /dev/null
* * * * * root perl /home/usm_cabletest/usm_cabletest.pl &> /dev/null
* * * * * root perl /home/usm_cabletest/usm_cabletest.pl &> /dev/null
* * * * * root perl /home/usm_cabletest/usm_cabletest.pl &> /dev/null
* * * * * root perl /home/usm_cabletest/usm_cabletest.pl &> /dev/null

In the card of the device polled by the usm_cabletest module you can view the history of polling of this device by the module and the general table of device polling by clicking the corresponding link. Also in the table of ports in the card of this device you can see the last known cable lengths on the polled ports.

== Parameters ==

The module is configured in the '''usm_cabletest.conf''' file.

$usUrl - URL to ERP "UserSide"
$usApiKey - [[API]]-key to ERP "UserSide"
$logsPath - Path to the catalogue for module logs

$isSilence - Flag - hide notifications to the console when the module is running
$delay - Custom time delay from 0 to n-seconds after module start. Allows you to reduce the load on the server when using a large number of modules at the same time

The usm_cabletest module can be run with the ''(specify a specific device to poll)'' parameter

Example:

perl usm_cabletest 998

will poll the switch with ID 998

== Operation information ==

On the "Settings - Modules - usm_cabletest" page you can view the report of polling by the equipment module by clicking on the link
***

Separately, you can view the data for this device in the equipment card
***

The latest data is displayed in the ports table
***

In the home page setting - the user can enable the output of cable length change information to the home page
***

***

== If the information is not captured/module does not work ==

1. It is necessary to distinguish and understand whether the module is not working or information is not captured. On the "Settings - Modules - usm_cabletest - Module Run Information" page, you should check the usm_cabletest module run logs and results.

2. You should make sure that the community access, passwords are correct and the device itself is physically connected and working.

3. In the ERP "UserSide" itself, open the switch card and click on the "Cable tester" link

4. For the test - you should run the module specifically for a particular switch. For example:

perl usm_cabletest.pl 998

will start the module for switch ID: 998

Check if there are no errors in the information output.

In the log files, analyse the information received.