ИНСТРУКЦИЯ АДМИНИСТРАТОРА КОСКО МЕССЕНДЖЕРА

1. Введение

Настоящая инструкция устанавливает порядок настройки и запуска программного обеспечения КОСКО-мессенджер.

2. Подготовка к запуску

2.1. Обновите и загрузите актуальные пакеты в системе:

Альт Сервер 10

Ubuntu linux

#apt-get update

#apt update

#apt-get dist-upgrade

#apt upgrade

2.2. Установите и запустите Docker и Docker Compose:

Альт Сервер 10

Ubuntu linux

Установка docker-engine:

#apt-get install docker-engine

См. руководство по установке службы Docker на Ubuntu

Активация службы:

#systemctl enable —now docker

Установка docker-compose:

#apt-get install docker-compose-v2

2.3. Создайте на диске следующие папки:

  • /cosco - для хранения файлов мессенджера (лицензии, сертификаты).

  • /opt/cosco_msg - для хранения конфигурационных файлов.

2.4. Перенесите файлы:

  • В /cosco:

    • файл лицензии (license.enc),

    • выпущенные TLS-сертификаты (fullchain.pem, privkey.pem),

    • файл конфигурации БД (postgresql.conf).

  • В /opt/cosco_msg:

    • docker-compose.yml,

    • .env,

    • update.sh (если установка выполняется без доступа в интернет).

2.5. Отредактируйте файл .env:

Укажите USE_LDAP_TLS=TRUE, если ваш LDAP-сервер использует TLS, иначе оставьте FALSE (значение по умолчанию).

3. Настройка сквозной аутентификации доменных пользователей

3.1. Создайте DNS запись типа А в зоне прямого просмотра

(например, srv-cosco-msg).

Рисунок 1. Пример созданной DNS-записи

3.2. Создайте пользователя в домене (например, cosco-auth).

3.3. Запустите командную строку от имени администратора на контроллере домена:

  • Сгенерируйте SPN запись:

setspn -S HTTP/srv-cosco-msg.domain.local@DOMAIN.LOCAL cosco-auth

Важно: SPN создается именно на A запись, сгенерированную в пункте 3.1.

  • Сгенерируйте keytab:

ktpass -princ HTTP/srv-cosco-msg.domain.local@DOMAIN.LOCAL -mapuser cosco-auth -pass ВАШ_ПАРОЛЬ -ptype KRB5_NT_PRINCIPAL -out c:\krb5.keytab -crypto ALL

3.4. Скопируйте krb5.keytab на сервер мессенджера в каталог /cosco/krb5/ (папку krb5 необходимо создать).

3.5. Создайте файл /cosco/krb5/krb5.conf с содержимым:

[libdefaults]
dns_lookup_kdc = true
dns_lookup_realm = true
ticket_lifetime = 24h
renew_lifetime = 7d
forwardable = true
rdns = false
default_realm = DOMAIN.LOCAL # замените на свой домен
default_ccache_name = KEYRING:persistent:%{uid}

3.6. Добавьте в файл /opt/cosco_msg/.env параметр:

KERBEROS_DOMAIN="HTTP/srv-cosco-msg.domain.local@DOMAIN.LOCAL"

3.7. Продолжите установку мессенджера. При возникновении ошибок:

  • Ошибка: Error getting user from LDAP with Kerberos: ... Cannot find key ...

→ Перелогиньтесь на клиенте, либо выполните очистку кэша Kerberos:

Windows: klist purge

Linux: kdestroy && kinit

Ошибка при генерации keytab: Failed to set property 'UserPrincipalName'

→ Проверьте, не занят ли UPN:

Get-ADUser -Filter {UserPrincipalName -eq "HTTP/srv-cosco-msg.domain.local@DOMAIN.LOCAL"}

→ Удалите UPN у пользователя и повторите генерацию keytab.

4. Установка и настройка сервера КОСКО-Мессенджера

Перейдите в каталог с конфигурационными файлами

cd /opt/cosco_msg

4.1 Установка с доступом в интернет

Авторизуйтесь в реестре контейнеров:

docker login registry.abs95.ru

  • Login: abr-messenger

  • Password: password1!

Загрузите контейнеры и запустите приложение:

Альт Сервер 10

Ubuntu Linux

docker compose up -d

docker-compose up -d

Рисунок 2. Пример ожидаемого результата

4.2 Установка без доступа в интернет

  1. Загрузите полученные tar-архивы в каталог /opt/cosco_msg(см. Рисунок 3)

    Рисунок 3. Необходимое содержимое папки /opt/cosco_msg

  2. Запустите скрипт для загрузки контейнеров и запуска Docker Compose:bash update.sh

  3. При необходимости проверьте наличие загруженных контейнеров:docker images Количество контейнеров должно соответствовать количеству tar-архивов.

  4. При необходимости повторите запуск docker compose:

Альт Сервер 10

Ubuntu Linux

docker compose up -d

docker-compose up -d

Рисунок 4. Ожидаемый результат

5. Конфигурация КОСКО-Мессенджера в клиенте приложения

5.1. Открытие клиента мессенджера

  1. Узнайте адрес сервера мессенджера (IP или домен) в вашей локальной сети.

  2. Откройте браузер на ПК, находящемся в одной сети с сервером, и введите адрес сервера (например, 10.0.0.185).

  3. Войдите для первоначальной настройки под учётной записью администратора:

    • Логин: admin

    • Пароль: 12345

Рисунок 5. Страница входа

5.2.Настройка интеграции с Active Directory

  1. Откройте боковое меню, нажав на иконку пользователя в левом верхнем углу.

  2. Выберите пункт «Админ панель» (Рисунок 6).

    Рисунок 6. Открытие админ панели

  3. Во вкладке интеграции с AD введите:

    • Адрес сервера LDAP

    • baseDN

    • Домен

    • Логин и пароль пользователя с правами чтения AD

    • При необходимости – фильтры групп пользователей

    • Соотнесите обязательные атрибуты:

      • Имя → атрибут LDAP cn (если там хранится полное имя)

      • Логин → атрибут LDAP sAMAccountName

    • При желании добавьте дополнительные атрибуты (например, department для отображения отделов).

  4. Нажмите «Сохранить изменения» (Рисунок 7).

  5. Нажмите «Синхронизация LDAP» и дождитесь завершения (появится сообщение об успехе).

Рисунок 7. Введенные и сохраненные настройки для интеграции с Active Directory (данные отображены для примера, руководствуйтесь вашей настройкой Active Directory)

5.3. Авторизация пользователя из Active Directory

  1. Выйдите из текущего аккаунта (боковое меню → «Выйти»).

  2. Войдите в мессенджер под пользователем, созданным в AD.

5.4. Тестирование сокетного соединения

  1. Перейдите во вкладку «Пользователи».

  2. Выберите «Администратор».

  3. Отправьте любое сообщение (кнопка «Отправить» или Enter).

  4. Выйдите из аккаунта и заново войдите как администратор (логин admin, пароль 12345).

  5. Убедитесь, что появилось непрочитанное сообщение (Рисунок 8).

Рисунок 8. Пример отображения непрочитанного сообщения

5.5. Управление пользователями

В панели администратора перейдите на вкладку «Пользователи»:

  • Чтобы назначить права администратора, нажмите иконку «Карандаш» у нужного пользователя и установите флажок в колонке «Роли».

  • Чтобы ограничить количество одновременных сессий, измените значение в колонке «Ограничение авторизации».

Рисунок 9. Список зарегистрированных пользователей

6. Плагин «Уведомление»

6.1. Генерация токена для информационной системы (ИС)

  1. В панели администратора перейдите на вкладку «Настройка плагина уведомлений».

  2. Нажмите «Добавить Систему» (Рисунок 10).

  3. Введите название системы (будет отображаться у пользователей).

  4. При необходимости укажите ссылку для закрытия уведомления (если отличается от DELETE-ссылки в .env). На этот адрес будет отправлен POST-запрос с телом: { "notification_id": 1 }

  5. Нажмите «Сгенерировать токен».

  6. Нажмите «Сохранить изменения».

  7. Скопируйте полученный токен – он будет использоваться при создании и закрытии уведомлений (передаётся в заголовке token).

Рисунок 10. Отображение вкладки «Настройка плагина уведомлений»

6.2. Отправка уведомления (POST-запрос)

Адрес для запроса: https://your_messenger_domain_or_ip/plugins/api/v1/tasks

Тело запроса:

[
{
"message": {
"icon": "string",
"text": "string",
"markdown_text": "string",
"header": "string",
"notification_text": "string"
},
"priority": 0,
"notification_id": 0,
"type": "default",
"source": "string",
"links": [
{ "link": "string", "title": "string" }
],
"buttons": [
{ "link": "string", "type": "request", "title": "string", "action": 0 }
],
"user_login": "string",
"closing_check": false,
"delete_api": "string",
"send_to": "user",
"integration_list": [ "trueconf" ],
"priority_table": [
{ "show_interval": 10, "show_count": 0 }
],
"meta": { "additionalProp1": {} }
}
]

Описание атрибутов

Таблица 1. Описание тела запроса

№

Параметр

Тип данных

Обязательность

Описание

Варианты значений

1

message

Object

да

Объект с параметрами

1.1

message.icon

String

да

Логотип уведомления

Изображение в формате data url

1.2

message.text

String

да

Текст уведомления (игнорируется, если есть markdown_text).

1.3

message.markdown_text

String

нет

Текст уведомления с типом разметки Markdown. Данный ключ имеет более высший приоритет чем message.text. В этом случае message.text не отображается.

1.4

message.header

String

да

Заголовок уведомления.

1.5

message.notification_text

String

нет

Короткий текст для push-уведомления.

2

priority

Integer

да

Приоритет уведомления для отображения в мессенджере.

0 - низший

1 - низкий

2 - невысокий

3 - средний

4 - высокий

5 - очень высокий

3

notification_id

Integer

нет

Уникальный ID уведомления (может генерироваться сторонней ИС). Если удалить атрибут, то ID сгенерируется мессенджером.

4

type

String

нет

Тип уведомления

"default" – обычное

"critical" – критическое.

5

source

String

да

Источник уведомления (должен совпадать с заданным при генерации токена).

6

links

Array of objects

нет

Дополнительные ссылки, отображаются после кнопок.

6.1

links.link

String

да

Адрес дополнительной ссылки

6.2

links.title

String

да

Текст дополнительной ссылки

7

buttons

Array of objects

да

Массив активных кнопок в уведомлении

7.1

buttons.link

String

да

Ссылка при нажатии на кнопку.

7.2

buttons.type

String

да

Тип кнопки

request - отправка запроса по ссылке

direct - перенаправления пользователя по ссылке

move - напомнить позже

7.3

buttons.title

String

да

Текст кнопки.

7.4

buttons.action

Integer

да

Уникальный номер кнопки.

8

user_login

String

да

Логин получателя уведомления (LDAP)

9

closing_check

Boolean

нет

Определяет, требуется ли со стороны ИС подтверждение выполнения целевого действия после нажатия на уведомление.

Значения:

false — требуется подтверждение.

true — не требуется, уведомление закрывается автоматически.

1. При closing_check = false

Система отправляет POST-запрос на адрес закрытия:

Приоритет 1: значение атрибута delete_api (указывается при создании токена ИС или в теле уведомления).

Приоритет 2: общий адрес из конфигурации мессенджера (TASKS_URL_DELETE в .env), если delete_api отсутствует.

ИС-отправитель должна обработать этот запрос и, когда задача выполнена, сама отправить в мессенджер POST-запрос:

/plugins/api/v1/tasks/cancel

{"tasks_id": [<id_уведомления>]}

(можно массив ID)

2. При closing_check = true

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

false - требуется подтверждение со стороны ИС

true - подтверждение не требуется

10

delete_api

String

нет

Переопределяет API для закрытия уведомления.

11

send_to

String

нет

Выбор режима отправки ведомления

"user" – конкретному пользователю

"all" – всем.

12

integration_list

Array of strings

нет

Массив с интеграциями

"trueconf" – дублировать уведомление в чат TrueConf.

13

priority_table

Array of objects

нет

Массив объектов, определяющих автоматическую смену приоритетов до выполнения целевого действия.

Уведомление (push) всплывает согласно этой матрице.

Для пропуска приоритета укажите null вместо объекта.

13.1

priority_table.show_interval

Integer

да

интервал между показами (в минутах)

13.2

priority_table.show_count

Integer

да

количество показов на данном приоритете

14

meta

Object

нет

Объект может содержать любые свойства, кроме явно описанных. Вы можете передавать дополнительные ключи по своему усмотрению. Позволяет искать уведомления через GET-запрос /plugins/api/v1/tasks/meta?key=...&value=....

Особенности работы

  • Ответ сервера — массив с ID созданных уведомлений и статусами. Порядок элементов соответствует порядку отправленных уведомлений.

    • Статус 200 — уведомление успешно создано.

    • Статус 409 — отправлен дубликат notification_id.

  • Массивом можно отправлять задачи только от одного источника (верификация по токену источника).

Пример ответа сервера:

[
{ "id": 123123, "status": 409 },
{ "id": 123123123, "status": 200 }
]

7. Установка и обновление Desktop версий

Для корректной работы десктопных версий для Windows и Linux необходимо:

7.1. Поместить следующие файлы в каталог /cosco/installer/:

  • cosco.zip — архив с актуальной версией для Linux.

  • latest-version.txt — текстовый файл с номером версии для Linux.

  • coscowin.zip — архив с актуальной версией для Windows.

  • latest-version-win.txt — текстовый файл с номером версии для Windows.

  • lic.pdf — PDF-файл лицензии мессенджера (отображается на клиенте).

  • Cosco.msi — установщик для первичной установки на Windows.

7.2. После запуска сервера мессенджера эти файлы становятся доступны по адресу http(s)://{your-cosco-domain}/downloads/ (см. Рисунок 11).

Рисунок 11. Перечень файлов в каталоге загрузок

7.3. Установка на Windows:

запустите Cosco.msi с правами администратора и выполните установку с параметрами по умолчанию.

7.4. Установка на Linux:

запустите скрипт install.sh с правами администратора:

sudo ./install.sh install

7.5. Обновление клиентов:

при появлении новых версий замените соответствующие архивы и текстовые файлы с версиями в каталоге /cosco/installer/. Запущенные клиенты регулярно сравнивают свою версию с версией на сервере и при несовпадении автоматически обновляются.

8. Работа с Desktop версией

8.1 «Тихий» запуск в Windows

Для запуска без графического интерфейса используйте ключи --silent или --background

Cosco.exe --silent

8.2. Протокол cosco://

Протокол регистрируется автоматически при первом запуске КОСКО‑Мессенджера. Позволяет осуществлять переход из внешней системы в конкретный диалог с пользователем по его логину:

cosco://user_login

9. Мониторинг в КОСКО Мессенджере

9.1. Метрики мониторинга доступны в панели администратора на вкладке «Мониторинг».

Отображаются:

  • количество пользователей в системе;

  • количество онлайн‑пользователей в разрезе типов клиентов;

  • график уведомлений, полученных от внешних систем через плагин уведомлений за прошедший период (см. Рисунок 12).

Рисунок 12. Мониторинг пользователей и уведомлений

9.2. На вкладке «Списки» доступны три раздела:

  1. «Установки» – перечень установок десктопных клиентов с информацией о версиях и устройствах (см. Рисунок 13).

  2. «Зарегистрированные» – все пользователи мессенджера с указанием последней сессии и её параметров (см. Рисунок 14).

  3. «Онлайн» – пользователи, находящиеся в сети в данный момент, с данными о типе клиента (см. Рисунок 15).

Рисунок 13. Список установок десктоп клиентов мессенджера
Рисунок 14. Список зарегистрированных пользователей
Рисунок 15. Список зарегистрированных пользователей

10 Распространение и обновление КОСКО Мессенджера

10.1. Распространение десктопных версий

  • Windows

    • Включите установку MSI‑пакета (Cosco.msi) в групповые политики для автоматической установки на рабочих станциях, где мессенджер отсутствует.

    • Для установки текущим онлайн‑пользователям используйте стандартную утилиту msiexec (например, msiexec /i Cosco.msi /quiet).

  • Linux

    • Выполните запуск скрипта install.sh с правами администратора на каждой рабочей станции (или централизованно через системы управления конфигурациями).

10.2. Обновление сервера

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

Дальнейший порядок действий:

  1. Остановите работающий сервер:cd /opt/cosco-msg docker-compose down

    Для Альт Сервер 10 используйте docker compose down.

  2. Замените файлы в каталоге /opt/cosco-msg**:**Поместите новые tar-файлы образов (например, registry.abs95.ru_cosco_msg_http.tar).При необходимости замените файл docker-compose.yml (если в новой версии изменились настройки).

  3. Загрузите новые образы в Docker:

  4. Запустите сервер с новыми образами:docker load -i registry.abs95.ru_cosco_msg_http.tar # пример имени Повторите для каждого нового образа. docker-compose up -d Для Альт Сервер 10: docker compose up -d.

  5. Проверьте статус контейнеров:

docker-compose ps

10.3. Обновление десктопных приложений

  1. Поместите актуальные файлы в каталог /cosco/installer/: cosco.zip, latest-version.txt, coscowin.zip, latest-version-win.txt, Cosco.msi

  2. В течение 30–60 минут клиенты на рабочих станциях автоматически обнаружат новую версию и выполнят обновление.