Модули userside

Модули предоставить не могу, но если они у вас уже есть, то вот как их можно использовать.

Как это работает

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

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

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

Вам нужно будет скопировать файлы модуля в подкаталог с модулями. Затем добавить в docker-compose.yaml в раздел services необходимый сервис для каждого из ваших модулей. После этого добавить запуск модуля в crontab, если этот модуль запускается периодинчески, выполняет полезную работу и завершается. В противном случае в crontab ничего не нужно добавлять и достаточно просто один раз запустить модуль командой запуска контейнера.

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

Каталог с файлами модуля на локальной хост-системе монтируется в контейнер в каталог /app. Именно из этого каталога будет запускаться модуль внутри контейнера. В примерах далее будет показано как монтировать каталог с модулем на примере расположения модуля в подкаталоге modules/usm_modulename, расположенном внутри основного каталога /opt/userside. Но вы можете расположить ваши модули в другом, удобном для вас месте и указать абсолютный путь при монтировании. Внутри контейнера этот путь всегда должен быть обязательно /app.

Путь к файлам логов в конфигурационном файле модуля должен быть /var/log/имя_модуля и обязательно должен совпадать с точкой монтирования в volumes для этого модуля в docker-compose.yaml. На самом деле, вы можете выбрать любой другой путь, если знаете что делаете. Главное, чтобы каталог, указанный в конфигурационном файле, был смонтирован в каталог на хост-системе.

Скопируйте файлы модуля в подкаталог modules/usm_modulename, где usm_modulename — название конкретного модуля. Внутри этого каталога должны быть файлы модуля без дополнительных подкаталогов.

Блок настроек для каждого модуля, добавляемый в docker-compose.yaml, должен добавляться внутрь раздела services с соответствующим отступом (вместо modulename должно быть имя используемого модуля).

Например:

services:
  userside:
    image: ...

  usm_modulename:
    image: uscr.duckdns.org/userside/usm_modulename_env
    volumes:
      - ./modules/usm_modulename:/app
      - ./modules/logs/usm_modulename:/var/log/usm_modulename
      - /etc/timezone:/etc/timezone:ro
      - /etc/localtime:/etc/localtime:ro

Предупреждение

Формат YAML чувствителен к форматированию. Следите за отступами.

Обязательные настройки модулей

В конфигурационном файле модуля (это может быть файл usm_название.conf или settings.ini или settings.yaml или любой другой файл конфигуарции модуля) нужно выполнить три обязательные настройки:

1. В переменной для указания userside_url укажите значение http://userside или http://userside/api.php (в зависимости как того требует модуль).

2. Укажите API-ключ (как его настроить — указани ниже в разделе «Настройка API-ключа»).

3. В переменной для указания пути к логам укажите /var/log/usm_modulename, где usm_modulename — это имя модуля. Этот каталог должен быть обязательно смонтирован в контейнере на какой-то каталог хоста, чтобы логи попадали в него.

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

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

Модули, образы окружений и типы запуска

Оф. документация по модулям.

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

Модуль	Есть образ	Тип запуска
usm_abills	usm_abills_env	периодический запуск
usm_asterisk	usm_asterisk_env	работает постоянно
usm_bgbilling	–	периодический запуск
usm_billing	доступен официально	периодический запуск
usm_cabletest	usm_cabletest_env	периодический запуск
usm_checker	usm_checker_env	периодический запуск
usm_gps	–	работает постоянно
usm_hydra	–	периодический запуск
usm_iferr	–	периодический запуск
usm_lanbilling	usm_lanbilling_env	периодический запуск
usm_nodeny	–	периодический запуск
usm_nodeny_plus	usm_nodeny_plus_env	периодический запуск
usm_observer	usm_observer_env	периодический запуск
usm_peleng	usm_peleng_env	периодический запуск
usm_pon	usm_pon_env	периодический запуск
usm_radio	usm_radio_env	периодический запуск
usm_stat	usm_stat_env	периодический запуск
usm_utm5	–	периодический запуск

Если вы желаете использовать готовые образы для окружений запуска модулей из Docker-репозитория uscr, то перед именем образа из таблицы вам нужно добавить uscr.duckdns.org/userside/. Именно такой пример имен образов используется далее в описании настройки (на примере образа окружения для модуля usm_abills):

services:
  usm_abills:
    image: uscr.duckdns.org/userside/usm_abills_env
    ...

Вместо использования готовых образов окружений вы можете построить контейнеры самостоятельно на основе готовых Dockerfile. Этот вариант описан внизу страницы.

Настройка API-ключа

Перед тем как использовать модули нужно подключить к контейнеру файл с конфигурацией API-ключей.

1. Скопировать файл modules/config.php из архива с примерами в каталог /docker/userside и настроить в нем API-ключ(и), как указано в документации: https://wiki.userside.eu/UserSide_API_Key.

   sudo curl http://uscr.duckdns.org/config.tgz -o config.tgz
   sudo tar xzf config.tgz
   sudo cp config-examples/config.php ./
   

2. Отредактировать файл config.php, указав там ваш секретный ключ доступа вместо фразы «сюда-вписать-сложный-ключ».

3. Остановить набор контейнеров userside:

   docker compose stop
   

4. Отредактировать docker-compose.yaml. Добавить для сервиса userside запись:

   services:
     userside:
       volumes:
         - ./config.php:/userside/userside3/main/config/config.php:ro
   

   Предупреждение

   Формат YAML чувствителен к форматированию. Следите за отступами.

5. Запустить набор контейнеров userside:

   docker compose up -d
   

Примеры настройки окружений

Модули с периодическим запуском

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

Далее будет приведен пример настройки модуля usm_abills.

По такому же принципу настраиваются и все остальные модули, для которых необходим периодический запуск по расписанию (cron) или вручную. Если вам нужно запустить, например, модуль usm_peleng, то в следующих инструкциях замените usm_abills на usm_peleng. Периодичность запуска в crontab смотрите в описании каждого из модулей в официальной документации.

1. Создать подкаталог для модуля и скопировать в него файлы модуля (источник файлов укажите самостоятельно):

   sudo mkdir -p /opt/userside/modules/usm_abills/logs
   sudo cp usm_abills.php /opt/userside/modules/usm_abills/
   sudo cp usm_abills.conf.php /opt/userside/modules/usm_abills/
   

2. В файл /opt/userside/modules/usm_abills/usm_abills.conf.php внесите следующие изменения:

   • $usersideUrl = "http://userside";

   • $usersideApiKey = "api-ключ";

   • $logPath = "/var/log/usm_abills";

   Остальные настройки выполните в соответствии с инструкцией на модуль.

3. Добавить в docker-compose.yaml внутрь раздела services следующий блок:

   usm_abills:
     image: uscr.duckdns.org/userside/usm_abills_env
     volumes:
       - ./modules/usm_abills:/app
       - ./modules/logs/usm_abills:/var/log/usm_abills
       - /etc/timezone:/etc/timezone:ro
       - /etc/localtime:/etc/localtime:ro
   

   Предупреждение

   Формат YAML чувствителен к форматированию. Следите за отступами.

4. Запустить модуль вручную, чтобы убедиться в работе:

   docker compose run --rm usm_abills
   

5. Если тестовый запуск прошел нормально, добавить crontab системы:

   */10 * * * *    root    /usr/bin/docker compose -f /opt/userside/docker-compose.yaml -T run --rm usm_abills
   

Модули, работающие постоянно

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

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

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

1. Создать подкаталог для модуля и скопировать в него файлы модуля (источник файлов укажите самостоятельно):

   sudo mkdir -p /opt/userside/modules/usm_asterisk/logs
   sudo cp usm_asterisk.pl /opt/userside/modules/usm_asterisk/
   sudo cp usm_asterisk.conf /opt/userside/modules/usm_asterisk/
   

   Файл usm_asterisk_control.pl не нужен. Его можно не копировать.

2. В файл /opt/userside/modules/usm_asterisk/usm_asterisk.conf внесите следующие изменения:

   • $zusapiurl = "http://userside/api.php";

   • $zusapikey = "api-ключ";

   • $ps_logpath = "/var/log/usm_asterisk";

   Остальные настройки выполните в соответствии с инструкцией на модуль.

3. Добавить в docker-compose.yaml внутрь раздела services следующий блок:

   usm_asterisk:
     image: uscr.duckdns.org/userside/usm_asterisk_env
     restart: unless-stopped
     volumes:
       - ./modules/usm_asterisk:/app
       - ./modules/logs/usm_asterisk:/var/log/usm_asterisk
       - /etc/timezone:/etc/timezone:ro
       - /etc/localtime:/etc/localtime:ro
   

   Предупреждение

   Формат YAML чувствителен к форматированию. Следите за отступами.

4. Запустить контейнер. В планировщик добавлять не нужно — контейнер запускается один раз и работает выполняется постоянно, а не по расписанию:

   docker compose up -d usm_asterisk
   

usm_billing

Документация.

Бесплатный модуль usm_billing доступен публично в виде докер-образа. Для использования этого модуля не нужно копировать файлы самого модуля, т.к. они уже находятся в официальном Docker-контейнере.

1. Создать подкаталог для логов модуля:

   sudo mkdir -p /opt/userside/modules/usm_billing/logs
   

2. Добавить в docker-compose.yaml внутрь раздела services следующий блок:

   usm_billing:
     image: erpuserside/usm_billing
     depends_on:
       - userside
     environment:
       USERSIDE_API_URL: http://userside
       USERSIDE_API_KEY: "указать api-ключ из файла config.php"
       BILLING_NAME: ""
       BILLING_URL: ""
       BILLING_ID: ""
       IS_DISABLE_CREATE_ADDRESS: 0 # Flag - Disable Create New Address Object (house, street etc) [0|1]
       IS_SKIP_UPDATE_AGREEMENT_DATE: 0 # Flag - Is Skip Update Agreement Date
       IS_SKIP_UPDATE_DATE_ACTIVITY: 0 # Flag - Is Skip Update Date Activity
       IS_SKIP_DELETE_EMPTY_IP: 0 # Flag - Is Skip Delete Empty Ip
       SKIP_DELETE_IP_LIST: "" # comma separated Diapazon Of Skipped Ip
       IS_IMPORT_LESS_ADDRESS: 0 # Flag - Is Update Empty Customer Address
       IS_IMPORT_LESS_PHONE: 0 # Flag - Is Update Empty Customer Phone
       IS_UPDATE_EMPTY_LEVEL: 0 # Flag - Is Update Empty Customer Level
       IS_UPDATE_EMPTY_ENTRANCE: 0 # Flag - Is Update Empty Customer Entrance
       IS_SKIP_UNUSED_ADDRESS: 0 # Flag - Is Skip Unused Address
       IS_USE_STREET_FULL_NAME: 0 # Flag - use the full name of the imported street (with suffix/prefix)
       IS_IMPORT_MESSAGE: 0 # Flag - import customer messages (if posible)
       ALWAYS_SET_CUSTOMER_GROUP_ID: "" # set the group ID for all imported customers
     volumes:
       - ./modules/logs/usm_billing:/module/log
       - /etc/timezone:/etc/timezone:ro
       - /etc/localtime:/etc/localtime:ro
   

3. Запустить модуль вручную, чтобы убедиться в работе:

   docker compose run --rm usm_billing
   

4. Если тестовый запуск прошел нормально, добавить crontab системы:

   */10 * * * *    root    /usr/bin/docker compose -f /opt/userside/docker-compose.yaml run --rm usm_billing
   

Самостоятельное построение контейнеров

Если у вас уже нет доступа к репозиторию uscr или если вы хотите самостоятельно построить контейнеры, то скачайте архив с готовыми Dockerfile и используйте их для построения контейнеров с окружениями для модулей.

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

cd /opt/userside
sudo curl http://uscr.duckdns.org/module-dockerfiles.tgz -o module-dockerfiles.tgz
sudo tar xzf module-dockerfiles.tgz

В docker-compose.yaml вместо указания образа из репозитория uscr вам нужно указать путь к Dockerfile для сборки.

Вместо:

services:
  usm_modulename:
    image: uscr.duckdns.org/userside/usm_modulename_env
    ...

используйте:

services:
  usm_modulename:
    build:
      context: module-dockerfiles/usm_modulename_env
    ...

Вместо modulename нужно указать настоящее имя нужного модуля.

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

Но, если вам по какой-то причине нужно построить контейнер до запуска или если изменялся файл Dockerfile, то построить контейнер можно следующей командой:

docker compose build usm_modulename

Все остальные инструкции остаются неизменными.