Установка серверной части приложения#

Данный раздел содержит информацию для быстрого развертывания серверной части приложения с использованием одного физического сервера и одной ноды Docker Swarm.

Загрузка установщика#

Для начала нужно скопировать установщик с git-репозитория. Установщик представляет из себя набор скриптов и файлов-конфигураций, позволяющих быстро настроить и развернуть приложение.

git clone https://github.com/getCompass/onpremise-installer

Подготовка установщика#

Перейдите в директорию установщика командой:

cd onpremise-installer

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

python3 script/create_configs.py

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

Конфигурация баз данных#

Стандартным режимом работы Compass On‑premise является использование собственных баз данных, поставляемых вместе с приложением. Если поставляемые БД не подходят для использования, то приложение может использовать внешние базы данных, указанные пользователем.

Примечание

Если вы планируете использовать Compass On‑premise в стандартном режиме, этот раздел можно пропустить.

Конфигурирование пользовательских баз данных

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

Compass On‑premise использует базу данных MySQL 8.0. Другие базы данных не поддерживаются приложение. Для обеспечения работы потребуется минимум два экземпляра базы данных: сервисная база данных и база данных пространства для общения. Для каждого дополнительного пространства для общения необходимо добавить еще один экземпляр. Таким образом для развертывания приложения с пятью пространствами для общения потребуется шесть экземпляров MySQL 8.0.

Требования к экземплярам пользовательских БД:

  • В качестве БД должна использоваться MySQL 8.0.

  • Подключение к БД должно осуществляться без TLS.

  • Должен быть доступен root пользователь с авторизацией по паролю.

  • У root пользователя должны быть права на создание пользователей и выдачу им разрешений.

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

Настройки баз данных находятся в файле configs/database.yaml. Откройте его любым текстовым редактором и выполните конфигурирование.

database_connection:

  # Выбранный режим работы приложения, для подключения приложения
  # к пользовательским БД необходимо указать в качестве driver значение "host".
  driver: "host"

  # Параметры выбранного способа подключения к БД.
  driver_data:
    project_mysql_hosts:

      # Системная база данных. Хранит в себе информацию данные учетных записей,
      # данные системных файлов и файлов по умолчанию, сервисные данные команд,
      # сервисные данные ВКС и системную информацию.
      monolith:
        host: "sys.bd.host"
        port: 3306
        root_password: "strong-one-sys"

      # Базы данных команд. Каждой команде необходимо выделить собственную БД.
      # Хранит в себе данные переписок, данные карточек сотрудников и данные
      # пользовательских файлов.
      company_mysql_hosts:

      # Параметры подключения для первой команды, которая будет создана по умолчанию.
      - host: "team.bd.host"
        port: 3306
        root_password: "strong-one-team1"
      # Параметры подключения для второй команды, которую
      # можно создать после развертывания приложения.
      - host: "team.bd.host"
        port: 3307
        root_password: "strong-one-team2"

Требования к параметрам подключений:

  • Не должно быть пересекающихся подключений, т.е. не должно быть нескольких экземпляров с одинаковыми параметрами host и port.

  • В момент установки базы должны быть запущены и доступны с сервера, на котором выполняется установка.

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

Шифрование сообщений#

Compass On‑premise поддерживает механизм шифрования сообщения, позволяющий избегать открытого представления содержимого чатов в базе данные или в файлах резервных копий баз данных. По умолчанию данный функционал выключен.

Примечание

Если вы не планируете включать шифрование сообщений, этот раздел можно пропустить.

Конфигурирование шифрования сообщений

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

Шифрование сообщений является ресурсоемкой задачей. Сервер должен удовлетворять минимальным системным требованиям для включения этой функции.

Шифрование сообщений обеспечивается алгоритмом AES-256-CBC. При шифровании используется случайный инициализирующий вектор и пользовательский ключ шифрования.

Для определения пользовательского ключа шифрования потребуется сгенерировать два ключа длиной 256 бит:

  • ключ шифрования данных;

  • мастер ключ.

Ключ шифрования данных является ключом, которым будут шифроваться сообщения. Его утеря приведет к невозможности расшифровать зашифрованные данные в БД. Ключ шифрования данных не должен храниться на том же сервере, где развернуто приложение. Рекомендуемым сценарием работы является создание ключей в пределах доверенного контура и вставка их base64 представлений в утилиту генерации секретов приложения.

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

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

Рекомендуемый способ доставки ключей в приложение#

  1. В доверенном контуре создайте файл с двоичным представлением ключа шифрования данных:

    openssl rand -out <путь к файлу с ключом шифрования данных> 32

  2. Выведите base64 представление ключа шифрования данных и сохраните для дальнейшей работы.

    cat <путь к файлу с ключом шифрования данных> | base64

  3. На сервере приложения создайте файл с двоичным представлением мастер ключа:

    openssl rand -out <путь к файлу с мастер ключом> 32

  4. Выведите base64 представление мастер ключа и сохраните его для дальнейшей работы.

    cat <путь к файлу с мастер ключом> | base64

  5. На сервере приложения запустите скрипт генерации секретов приложения:

    sudo python3 script/create_secret.py

Выберите из предложенного списка секрет «Ключ-секрет шифрования БД». Для обоих ключей выберите base64 представление и введите ранее сохраненные строковые значения. Убедитесь, что скрипт корректно отработал и создал секрет.

Если рекомендуемый способ не подходит#

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

  1. Сгенерируйте файл с ключом шифрования данных длиной 256 бит.

  2. Сгенерируйте файл с мастер ключом длиной 256 бит.

  3. Зашифруйте ключ шифрования данных в ключ-секрет с помощью мастер ключа. Важно использовать именно указанный способ.

    openssl aes-256-cbc -pbkdf2 -kfile <файл с мастер ключом> -in <файл с ключом шифрования данных> -out <выходной файл>

  4. Выведите base64 представление ключа-секрета:

    cat <выходной файл> | base64

  5. Создайте Docker secret c ключом-секретом:

    echo '<base64 представление ключа-секрета>' | sudo sudo docker secret create compass_database_encryption_secret_key -

  6. Выведите base64 представление мастер ключа и используйте его во время конфигурирования:

    cat <файл с мастер ключом> | base64

Конфигурирование приложения#

Настройки шифрования базы данных находятся в файле configs/database.yaml. Откройте его любым текстовым редактором и выполните конфигурирование.

# Параметры шифрования базы данных. Приложение шифрует данные сообщений
# и комментариев до передачи данных в БД. Таким образом получение
# доступа к БД или к резервной копии не даст доступа к содержимому переписок.
database_encryption:

    # Режим шифрования (none, read_write, read).
    mode: "read_write"

    # Мастер-ключ шифрования. Данные не будут зашифрованы этим ключом, данный ключ используется
    # для расшифровывания ключа-секрета во время исполнения.
    master_key: "<base64 представление мастер-ключа>"

Конфигурация правил регистрации участников#

Compass On‑premise предлагает следующие способы создания и аутентификации учетных записей:

  • с использованием номера телефона;

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

  • с использованием SSO.

Для работы приложения необходимо выбрать как минимум один из способов регистрации/аутентификации. Соответствующая настройка находится в файле configs/auth.yaml. Откройте его любым текстовым редактором и укажите желаемый способ.

# Доступные способы аутентификации. Возможные варианты:
# phone_number – по номеру телефона с подтверждением SMS-кода;
# mail – по электронной почте с паролем и кодом подтверждения;
# sso – через сервис Single Sign-On;
available_methods: ["phone_number", "mail", "sso"]

Примечание

Можно указать как один способ, так и несколько. Обратите внимание, что значение всегда должно быть массивом строк, даже если вы выбрали один способ регистрации/аутентификации. В случае указания единственного способа в массиве должен быть один элемент.

В этом разделе конфигурации можно установить ограничения на авторизацию в приложении в зависимости от типа устройства пользователя. Настройки находятся в файле configs/auth.yaml. Откройте его любым текстовым редактором и выполните настройку.

# Запрещено ли пользователям с ПК авторизовываться в приложении.
auth.is_desktop_prohibited: false

# Запрещено ли пользователям с iOS авторизовываться в приложении.
auth.is_ios_prohibited: false

# Запрещено ли пользователям с Android авторизовываться в приложении.
auth.is_android_prohibited: false

Конфигурация Captcha#

Если вы планируете использовать Captcha для дополнительной защиты от спама, необходимо настроить один из следующих сервисов:

Настройки капчи находятся в файле captcha.yaml. Откройте его любым текстовым редактором и выполните настройку.

# Включена ли опция проверки капчи при достижении лимита попыток аутентификации.
captcha.enabled: true

# Кол-во попыток аутентификации, после которых запрашивается разгадывание капчи.
# При значении = 0 – каждая попытка аутентификации запрашивает разгадывание капчи.
captcha.require_after: 2
Конфигурация Google Recaptcha
# Идентификатор проекта Google Recaptcha.
# В документации по подключению Google Recaptcha обозначено как Project ID.
google_captcha.project_id: "<id проекта из панели управления Google>"

# Общий ключ Google Recaptcha. Данный ключ будет использоваться
# для всех клиентских платформ, кроме тех, для которых задан выделенный ключ.
# В документации по подключению Google Recaptcha обозначено как общий ключ.
google_captcha.default_client_key: "<ваш общий ключ из панели Google Recaptcha>"

# Выделенный ключ Google Recaptcha для платформы Android (Google Play).
# Данный ключ будет использоваться только для приложения, установленного через Google Play.
# Использование выделенного ключа для Google Play версии приложения является необходимым требованием.
# В документации по подключению Google Recaptcha обозначено как ключ платформы андроид.
google_captcha.android_client_key:  "<ключ платформы Android>"

# Выделенный ключ Google Recaptcha для платформы iOS (Apple Store).
# Данный ключ будет использоваться только для приложения, установленного через AppStore.
# Использование выделенного ключа для AppStore версии приложения является необходимым требованием.
# В документации по подключению Google Recaptcha обозначено как ключ платформы iOS.
google_captcha.ios_client_key: "<ключ платформы iOS>"

# Выделенные ключи клиентских платформ.
# Не являются обязательными, в большинстве случаев их указывать нет необходимости.
google_captcha.huawei_client_key: "<ключ платформы Huawei>"
google_captcha.electron_client_key: "<ключ платформы Electron>"

# Серверный ключ Google Recaptcha.
# Данный ключ используется приложением для идентификации в Google Recaptcha.
# В документации по подключению Google Recaptcha обозначено как серверный ключ.
google_captcha.server_key: "<ваш серверный ключ из панели Google Recaptcha>"
Конфигурация Yandex SmartCaptcha
# Клиентский ключ Yandex SmartCaptcha. Данный ключ будет использоваться
# для всех клиентских платформ.
# В документации по подключению Yandex SmartCaptcha обозначено как ключ клиента.
yandex_captcha.default_client_key: "<ваш клиентский ключ из панели Yandex SmartCaptcha>"

# Серверный ключ Yandex SmartCaptcha.
# Данный ключ используется приложением для идентификации в Yandex SmartCaptcha.
# В документации по подключению Yandex SmartCaptcha обозначено как ключ сервера.
yandex_captcha.server_key: "<ваш серверный ключ из панели Yandex SmartCaptcha>"

Конфигурация почтового сервиса#

Если вы указали электронную почту как способ регистрации/аутентификации, необходимо провести настройку почтового сервиса. Настройки почтового сервиса находятся в файле configs/auth.yaml. Откройте его любым текстовым редактором и выполните настройку.

# Список доменов почтовых адресов, для которых разрешена аутентификация в приложении.
# Если список пуст, то аутентификация разрешена для всех доменов. Если вы хотите ограничить
# регистрацию корпоративными почтовыми доменами, то необходимо их указать (не больше трех).
mail.allowed_domains: []

# Включена ли опция подтверждения почты при регистрации через проверочный код.
# Требует обязательную конфигурацию доставки email писем в разделе smtp ниже.
mail.registration_2fa_enabled: true

# Включена ли опция подтверждения почты при авторизации через проверочный код
# Требует обязательную конфигурацию доставки email писем в разделе smtp ниже.
mail.authorization_2fa_enabled: true

# Отправка писем осуществляется по SMTP протоколу.
# Параметры ниже требуют указания SMTP сервера, через который будут доставляться email письма.
# Если в поле password используются двойные кавычки, необходимо их экранировать, пример: example\"pass.
smtp.host: "smtp.awesome-company.ru"
smtp.port: 465
smtp.username: "awesome-company"
smtp.password: "very-strong-password"

# Тип шифрования соединения. Возможные значения: tls, ssl.
smtp.encryption: "ssl"

# Электронный адрес отправителя.
smtp.from: "mail@awesome-company.ru"

Примечание

Для ограничения регистрации/авторизации с использованием электронной почты в рамках корпоративного домена необходимо указать название домена в поле mail.allowed_domains. Обратите внимание, что значение поля всегда должно быть массивом, даже если вы указываете один домен. В случае указания единственного домена в массиве должен быть один элемент.

Конфигурация SSO#

Если вы указали SSO как способ регистрации/аутентификации, необходимо настроить связь SSO-сервиса и приложения Compass On‑premise. Все необходимые данные можно получить, выполнив указания из пункта настройка SSO-авторизации. Настройки SSO находятся в файле configs/auth.yaml.

# Укажите протокол, который будет использоваться для аутентификации. Возможные варианты:
# "oidc" – протокол OpenID Connect
# "ldap" – протокол Lightweight Directory Access Protocol
sso.protocol: "ldap"

# Кастомизация текста кнопки для запуска аутентификации через SSO на веб-сайте On-Premise решения
sso.web_auth_button_text: "Войти через корп. портал (SSO LDAP)"

# Включена ли опция альтернативных способов аутентификации при аутентификации через SSO.
# При включенной опции у пользователей, прошедших аутентификацию через SSO,
# появляется возможность аутентификации через другие способы аутентификации,
# описанных в available_methods в текущем конфигурационном файле.
sso.authorization_alternative_enabled: false

# Включена ли опция актуализации данных о пользователях в Compass каждый раз, когда они успешно авторизуются
# в приложении через SSO.
sso.profile_data_actualization_enabled: true

# Автоматическое вступление пользователей после регистрации через SSO/LDAP в первую команду на сервере.
# От лица администратора будет создана бессрочная ссылка-приглашение с заданным параметром вступления в команду.
# Параметр принимает следующие значения:
# member – пользователи автоматически вступают как участники;
# guest – пользователи автоматически вступают как гости;
# moderation – отправляется заявка на вступление в команду, требующая подтверждение от администратора;
# disabled – опция автоматического вступления в первую команду выключена.
sso.auto_join_to_team: "member"

Для сопоставления атрибутов учетной записи SSO с атрибутами профиля пользователей в Compass необходимо заполнить настройки в файле configs/auth.yaml. Откройте его любым текстовым редактором и выполните настройку.

# Сопоставление атрибутов учетной записи SSO с атрибутами профиля пользователя в Compass.
# Это необходимо для автоматического заполнения информации о пользователе при его регистрации
# через SSO.
#
# Поле "sso.compass_mapping.name:" обязательно к заполнению, остальные поля могут быть пустыми, если атрибут не требуется.
#
# Атрибуты, которые требуется подтягивать из SSO по протоколу OIDC/LDAP указываются в фигурных скобках {attribute_name},
# например, для ФИО в Compass можно сопоставить атрибуты следующим образом:
# "sso.compass_mapping.name: "{first_name} {last_name}"".

sso.compass_mapping.name: "<название атрибута из SSO>"
sso.compass_mapping.avatar: "<название атрибута из SSO>"
sso.compass_mapping.badge: "<название атрибута из SSO>"
sso.compass_mapping.role: "<название атрибута из SSO>"
sso.compass_mapping.bio: "<название атрибута из SSO>"

Для подключения аутентификации по протоколу OpenID Connect необходимо заполнить настройки в файле configs/auth.yaml. Откройте его любым текстовым редактором и выполните настройку.

# ID и секретный ключ клиентского приложения, зарегистрированных в SSO провайдере.
oidc.client_id: "<ваш Client Identifier>"
oidc.client_secret: "<ваш Secret>"

# Ссылка на метаданные SSO провайдера.
oidc.oidc_provider_metadata_link: "<ссылка, по которой доступна meta-data>"

# Сопоставление атрибутов учетной записи SSO с атрибутами профиля root-пользователя в Compass.
# Это необходимо для корректной аутентификации root-пользователя при первой авторизации в Compass On-premise.
# Необходимо заполнить минимум одно поле.
oidc.attribution_mapping.mail: "<название атрибута из SSO>"
oidc.attribution_mapping.phone_number: "<название атрибута из SSO>"

Для подключения аутентификации по протоколу LDAP необходимо заполнить настройки в файле configs/auth.yaml. Откройте его любым текстовым редактором и выполните настройку.

# Хост сервера LDAP.
ldap.server_host: "<Хост вашего LDAP сервера>"

# Порт сервера LDAP.
ldap.server_port: 636

# Нужно ли устанавливать SSL соединение
ldap.use_ssl: true

# Контекст поиска пользователей в LDAP каталоге.
ldap.user_search_base: "ou=users,dc=example,dc=com"

# Название атрибута учетной записи LDAP, значение которого будет использоваться в качестве username в форме авторизации.
# Значение этого атрибута должно быть уникальным для каждой учетной записи.
#
# Для Active Directory – "sAMAccountName"
# Для FreeIPA – "uid"
ldap.user_unique_attribute: "uid"

# Фильтр для поиска учетной записи LDAP в момент авторизации пользователя в приложении.
# Параметр обязательно должен содержать уникальный атрибут, например (attribute_name={0}), где
# вместо attribute_name указывается название атрибута, по которому будет осуществляться поиск учетной записи.
# Необязательный параметр. Используйте его при необходимости фильтрации пользователей по критериям.
# Например:
# Для Active Directory: "(&(objectClass=person)(sAMAccountName={0}))"
# Для Active Directory с проверкой на принадлежность учетной записи к группе CompassUsers:
# "(&(objectClass=person)(sAMAccountName={0})(memberOf=CN=CompassUsers,DC=example,DC=com))"
# Для FreeIPA: "(&(objectClass=person)(uid={0}))"
ldap.user_search_filter:

# Полный DN (Distinguished Name) учетной записи LDAP, которая будет использоваться
# для поиска других учетных записей и мониторинга их удаления/блокировки в каталоге.
ldap.user_search_account_dn: "uid=compass_monitor,ou=users,dc=example,dc=com"

# Пароль учетной записи LDAP, которая будет использоваться
# для поиска других учетных записей и мониторинга их удаления/блокировки в каталоге.
ldap.user_search_account_password: "very-strong-password"

# Лимит неудачных попыток аутентификации, по достижению которых IP адрес пользователя получает блокировку на 15 минут.
ldap.limit_of_incorrect_auth_attempts: 5

# Включен ли мониторинг удаления / блокировки учетной записи LDAP для запуска автоматической
# блокировки связанного пользователя в Compass.
ldap.account_disabling_monitoring_enabled: true

# Уровень автоматической блокировки при отключении учетной записи LDAP,
# связанной с пользователем Compass.
# Возможные уровни:
# "light" – у связанного пользователя Compass закрываются все активные сессии, блокируется доступ к пространствам на вашем сервере.
# "hard"  – у связанного пользователя Compass закрываются все активные сессии, блокируется доступ к пространствам на вашем сервере,
#           пользователь покидает все команды.
ldap.on_account_disabling: "light"

# Уровень автоматической блокировки при полном удалении учетной записи LDAP,
# связанной с пользователем Compass.
# Возможные уровни:
# "light" – у связанного пользователя Compass закрываются все активные сессии, блокируется доступ к пространствам на вашем сервере.
# "hard"  – у связанного пользователя Compass закрываются все активные сессии, блокируется доступ к пространствам на вашем сервере,
#           пользователь покидает все команды.
# Если использовались почта или номер телефона для авторизации одновременно с LDAP, то в случае удаления учетной записи в LDAP,
# привязанная почта и номер пользователя станут недоступны для повторной регистрации/авторизации.
ldap.on_account_removing: "light"

# Временной интервал между проверками мониторинга блокировки пользователя LDAP.
#
# Ns – интервал каждые N секунд
# Nm – интервал каждые N минут
# Nh – интервал каждые N часов
ldap.account_disabling_monitoring_interval: "5m"

# Количество подгружаемых учетных записей из LDAP за один запрос в механизме мониторинга удаления/блокировки учетной записи LDAP.
# Обязателен к заполнению в случае включенного параметра ldap.account_disabling_monitoring_enabled.
# Зачастую подходит значение по умолчанию, если в настройках LDAP-провайдера не было установлено ограничение ниже текущего значения.
ldap.user_search_page_size: 1000

Примечание

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

sudo python3 script/update.py

Конфигурация SMS-сервиса#

Если вы указали номер телефона как способ регистрации/аутентификации, необходимо провести настройку сервиса отправки SMS-сообщений. В данный момент приложение поддерживает три поставщика услуг доставки SMS. Предварительно необходимо зарегистрировать аккаунт на сайте одного из поставщиков согласно инструкции:

Настройки SMS-провайдеров находятся в файле configs/auth.yaml. Откройте его любым текстовым редактором и выполните настройку SMS.

Настройка SMS-оператора СМС-Агент
# Массив обслуживаемых префиксов. Система оперирует номерами в международном формате и
# при выборе оператора опирается на префикс номера. Данный параметр определяет список
# обслуживаемых провайдером префиксов. Например, для обслуживания российских номеров необходимо
# указать префикс «+79», для белорусских «+375». Для обслуживания всех номеров укажите только «+».
sms_agent.provide_phone_code_list: ["+79", "+375"]

# Массив приоритетных обслуживаемых префиксов. Если один префикс закреплен за несколькими провайдерами,
# то система отдаст приоритет тому провайдеру, у которого префикс находится в списке приоритетных.
# Логика ввода значений аналогична логике поля sms_agent.provide_phone_code_list.
# Поле не является обязательным для заполнения.
sms_agent.high_priority_phone_code_list:

# Минимальный уровень баланса на счете оператора, после которого он перестает использоваться для рассылки
# SMS-сообщений. В большинстве случаев стоит оставить небольшой запас, чтобы счет не уходил в минус.
# В качестве валюты используется валюта счета, предоставленного SMS-провайдером.
sms_agent.min_balance_value: 1

# Точка входа, куда система будет отправлять API-запросы для рассылки SMS-сообщений. В большинстве случаев
# адрес по умолчанию является актуальными и не требует изменений.
# Значение по умолчанию: https://api3.sms-agent.ru/v2.0/
sms_agent.provider_gateway_url: "https://api3.sms-agent.ru/v2.0/"

# Имя приложения, используемого при отправке сообщений (для получателя SMS будет являться отправителем).
sms_agent.app_name: "Compass"

# Логин, который будет использоваться для авторизации в API SMS-провайдера. Логин выдается при подключении
# услуг SMS-провайдера. В документации подключения провайдера обозначен как login.
sms_agent.login: "<ваш login из личного кабинета провайдера СМС-Агент>"

# Пароль, который будет использоваться для авторизации в API SMS-провайдера. Пароль выдается при подключении
# услуг SMS-провайдера. В документации подключения провайдера обозначен как password.
sms_agent.password: "<ваш password из личного кабинета провайдера СМС-Агент>"
Настройка SMS-оператора Twilio
# Массив обслуживаемых префиксов. Система оперирует номерами в международном формате и
# при выборе оператора опирается на префикс номера. Данный параметр определяет список
# обслуживаемых провайдером префиксов. Например, для обслуживания номеров казахстана необходимо
# указать префиксы «+796» и «+797», для белорусских «+375». Для обслуживания всех номеров укажите только «+».
twilio.provide_phone_code_list: ["+796", "+797"]

# Массив приоритетных обслуживаемых префиксов. Если один префикс закреплен за несколькими провайдерами,
# то система отдаст приоритет тому провайдеру, у которого префикс находится в списке приоритетных.
# Логика ввода значений аналогична логике поля twilio.provide_phone_code_list.
# Поле не является обязательным для заполнения.
twilio.high_priority_phone_code_list:

# Минимальный уровень баланса на счете оператора, после которого он перестает использоваться для рассылки
# SMS-сообщений. В большинстве случаев стоит оставить небольшой запас, чтобы счет не уходил в минус.
# В качестве валюты используется валюта счета, предоставленного SMS-провайдером.
twilio.min_balance_value: 1

# Точка входа, куда система будет отправлять API-запросы для рассылки SMS-сообщений. В большинстве случаев
# адрес по умолчанию является актуальными и не требует изменений.
# При использовании оператора Twilio поле является обязательным.
# Значение по умолчанию: https://api.twilio.com/2010-04-01/
twilio.provider_gateway_url: "https://api.twilio.com/2010-04-01/"

# Уникальное имя отправителя. Получатели SMS будут видеть это имя как отправителя сообщения.
# При заполнении данного поля необходимо указать выбранное при подключении провайдера имя.
# В документации подключения провайдера обозначен как Alphanumeric.
twilio.app_name: "<выбранное имя отправителя из личного кабинета провайдера Twilio>"

# Идентификатор аккаунта, который будет использоваться для авторизации в API SMS-провайдера.
# Идентификатор выдается при подключении услуг SMS-провайдера. В документации подключения провайдера
# обозначен как Account SID.
twilio.account_sid: "<ваш Account SID из личного кабинета провайдера Twilio>"

# Токен, который будет использоваться для авторизации в API SMS-провайдера. Токен выдается
# при подключении услуг SMS-провайдера. В документации подключения провайдера обозначен как Auth Token.
twilio.account_auth_token: "<ваш Auth Token из личного кабинета провайдера Twilio>"
Настройка SMS-оператора Vonage
# Массив обслуживаемых префиксов. Система оперирует номерами в международном формате и
# при выборе оператора опирается на префикс номера. Данный параметр определяет список
# обслуживаемых провайдером префиксов. Например, для обслуживания номеров казахстана необходимо
# указать префиксы «+796» и «+797», для белорусских «+375». Для обслуживания всех номеров укажите только «+».
vonage.provide_phone_code_list: ["+796", "+797"]

# Массив приоритетных обслуживаемых префиксов. Если один префикс закреплен за несколькими провайдерами,
# то система отдаст приоритет тому провайдеру, у которого префикс находится в списке приоритетных.
# Логика ввода значений аналогична логике поля vonage.provide_phone_code_list.
# Поле не является обязательным для заполнения.
vonage.high_priority_phone_code_list:

# Минимальный уровень баланса на счете оператора, после которого он перестает использоваться для рассылки
# SMS-сообщений. В большинстве случаев стоит оставить небольшой запас, чтобы счет не уходил в минус.
# В качестве валюты используется валюта счета, предоставленного SMS-провайдером.
vonage.min_balance_value: 1

# Точка входа, куда система будет отправлять API-запросы для рассылки SMS-сообщений. В большинстве случаев
# адрес по умолчанию является актуальными и не требует изменений.
# Значение по умолчанию: https://rest.nexmo.com/
vonage.provider_gateway_url: "https://rest.nexmo.com/"

# Имя приложения, используемого при отправке сообщений (для получателя SMS будет являться отправителем).
vonage.app_name: "Compass"

# Ключ, который будет использоваться для авторизации в API SMS-провайдера.
# Ключ выдается при подключении услуг SMS-провайдера.
# В документации подключения провайдера обозначен как API key.
vonage.api_key: "<ваш API key из личного кабинета провайдера Vonage>"

# Секрет, который будет использоваться для авторизации в API SMS-провайдера. Секрет выдается при
# подключении услуг SMS-провайдера. В документации подключения провайдера обозначен как API Secret.
vonage.api_secret: "<ваш API Secret из личного кабинета провайдера Vonage>"

Конфигурация портов и доменов приложения#

Для корректной работы приложения необходимо указать настройки для безопасного сетевого взаимодействия. Соответствующие настройки находятся в файле configs/global.yaml. Откройте его любым текстовым редактором и выполните настройку.

# Имя сертификата для домена с доверенной подписью.
# Файл сертификата должен находиться в директории /etc/nginx/ssl.
nginx.ssl_crt: "<имя вашего сертификата без полного пути>"

# Имя ключа сертификата для домена с доверенной подписью.
# Файл ключ должен находиться в директории /etc/nginx/ssl.
nginx.ssl_key: "<имя вашего ключа для сертификата без полного пути>"

# IPv4 адрес сервера, на котором выполняется установка приложения. Внутренний трафик приложения
# будет пересылаться по этому адресу. Не используйте адрес 127.0.0.1, localhost и другие замыкающие адреса.
host_ip: "<IPv4 адрес вашего сервера>"

# Доменное имя, которое будет использоваться для доступа к приложению.
# Доменное имя должно быть доступно из внешней сети.
domain: "<ваше доменное имя>"

# Директория, где приложение будет хранить свои постоянные данные.
# Указываемая директория должна существовать и быть доступной для записи.
root_mount_path: "/home/compass"

Примечание

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

Порты, используемые приложением. Все настраиваемые порты передаются в Docker в момент развертывания. Docker делает expose внутренних портов контейнера, используя значения из конфигурации.

Внимание

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

Настройки безопасности портов по умолчанию с использованием Ubuntu Firewall
# Эти команды актуальны только для настроек по умолчанию.
# Если вы изменяете конфигурацию портов, то команды нужно выполнить для выбранных вами портов.

sudo ufw allow 10000/udp;

sudo ufw allow in on docker_gwbridge to any port 35150:35165 proto tcp;
sudo ufw allow in on docker_gwbridge to any port 31101 proto tcp;
sudo ufw allow in on docker_gwbridge to any port 31102 proto tcp;

sudo ufw deny 31101;
sudo ufw deny 31102;
sudo ufw deny 35150:35165/tcp;

# Внешний порт контейнера сайта аутентификации.
# Трафик сайта будет пересылаться на этот порт.
join_web.service.join_web.external_port: 31900

# Внешний порт контейнера Nginx.
# Трафик приложения будет пересылаться на этот порт.
monolith_nginx_port: 32100

# Внешний порт контейнера сервиса управления базами данных команд для общения.
# Запросы к сервису будут пересылаться на этот порт.
# Для безопасности этот порт должен быть недоступен извне.
domino.go_database_controller_port: 31101

# Внешний порт контейнера поискового инструмента Manticore Search.
# Для безопасности этот порт должен быть недоступен извне.
domino.service.manticore.external_port: 31102

# Диапазон портов, доступных приложению для создания баз данных команд для общения.
# Для безопасности эти порты должны быть недоступны извне.
company.start_port: 35150
company.end_port: 35165

# Порт для контейнера с веб-страницей присоединения к конференции.
# Внутренний трафик сайта будет пересылаться на этот порт.
jitsi_web.service.jitsi_web.external_port: 31901

# Порт для https запросов к веб-интерфейсу Jitsi.
# Запросы к веб-интерфейсу будут пересылаться на этот порт.
jitsi.service.web.https_port: 35000

# Порт для передачи мультимедиа-данных конференции в приложении.
# Порт будет выделен под RTP-соединения участников в конференции.
jitsi.service.jvb.media_port: 10000

# Необязательный параметр. Используйте его для указания IP-адреса или списка IP-адресов (через запятую),
# по которым клиенты будут подключаться к вашему медиа-серверу Compass On-Premise.
# Этот параметр особенно полезен, если сервер находится за NAT. В этом случае укажите публичный IP-адрес,
# а затем через запятую — IP-адрес, указанный в параметре `host_ip` выше.
jitsi.service.jvb.media_advertise_ips: "203.0.113.10,192.168.1.100"

# Порт для компонента jicofo, модуля для ВКС
jitsi.service.jicofo.port: 35001

# Порт для компонента prosody, модуля для ВКС
# Запросы к компоненту будут отправляться на этот порт.
jitsi.service.prosody.serve_port: 35002

Внимание

Если сервер с Compass развернут за NAT, выполните следующие действия:

  • Убедитесь, что порт 10000 UDP открыт на firewall, через который идет трафик. Если порт закрыт, откройте его.

  • В настройках DNAT настройте проброс порта 10000 UDP с внешнего IP-адреса на порт 10000 UDP сервера Compass во внутренней сети.

  • В конфигурационном файле global.yaml заполните поле jitsi.service.jvb.media_advertise_ips.

Параметры TURN-сервера для функционала аудио- и видеозвонков. В блоке ниже описаны параметры, которые подразумевают использование TURN-сервера по умолчанию. Если вы планируете использовать другой TURN-сервер, в блоке нужно указать соответствующие параметры.

# Адрес TURN сервера, который будет использоваться для соединения в ВКС.
jitsi.service.turn.host: "onpremise-turn.getcompass.ru"

# Порт TURN сервера, который принимает входящие UDP/TCP соединения клиентов.
jitsi.service.turn.port: 80

# Порт TURN сервера, который принимает входящие соединения клиентов, использующие протокол TLS.
jitsi.service.turn.tls_port: 443

# Секретный ключ TURN сервера.
jitsi.service.turn.secret: "<default-turn-secret-key>"

# Список используемых протоколов для соединения клиентов с TURN сервером.
# По умолчанию используется только UDP протокол для повышения качества
# видеоконференций в нестабильных сетях.
#
# ["udp"] – используется только UDP протокол;
# ["tcp"] – используется только TCP протокол;
# ["udp", "tcp"] – используются оба протокола.
jitsi.service.turn.use_protocols: ["udp"]

# Использовать ли принудительно TURN сервер для соединения в видеоконференция.
# По умолчанию флаг включен для повышения гарантии установления соединения.
jitsi.service.turn.force_relay: true

Параметры для подключения сервиса мониторинга ошибок Sentry.

# Необязательный параметр. Sentry DSN ключи для отправки аналитики об ошибках на клиентских платформах.
sentry_dsn_key_electron: ""
sentry_dsn_key_android: ""
sentry_dsn_key_ios: ""

Конфигурация Root‑пользователя#

Root‑пользователь является первым пользователем приложения. От его имени будут создаваться пространства. Он также является обычным пользователем и может пользоваться приложением. Root‑пользователь будет создан в процессе установки.

Настройки Root‑пользователя находятся в файле configs/team.yaml. Откройте его любым текстовым редактором и выполните конфигурацию.

# Полное имя главного (root) пользователя в приложении.
# С этим именем будет зарегистрирован первый пользователь в приложении.
# Также от имени этого пользователя будут создаваться все новые команды в приложении.
root_user.full_name: "Company Owner"

# Номер телефона главного (root) пользователя в приложении.
# Телефон указывается в международном формате (с «+» в начале).
# Номер можно будет изменить в интерфейсе приложения.
# Номер должен быть настоящим — без него невозможно будет выполнить авторизацию.
root_user.phone_number: "+79123456789"

# Почта и пароль главного (root) пользователя в приложении.
# Почта должна быть настоящей — без нее невозможно будет выполнить авторизацию.
# Почту и пароль можно будет изменить в интерфейсе приложения.
root_user.mail: "leader@awesome-company.ru"

# Пароль для авторизации по почте. Минимальная длина пароля 8 символов.
root_user.password: "very-strong-password"

# SSO логин используемый для авторизации через SSO.
# В поле необходимо указать почту или номер телефона, используемый при логине через SSO.
root_user.sso_login: "leader@awesome-company.ru"

# Название первой команды.
team.init_name: "Main"

Внимание

Данные конфигурации используются только для регистрации Root‑пользователя и создания первой команды. После успешного создания Root‑пользователя и первой команды изменение этих настроек не приведет к изменению данных в приложении.

Конфигурация разрешения редактирования профилей участников#

С помощью этого раздела конфигурации вы можете ограничить возможность редактирования данных профиля пользователями. Настройки разрешений находятся в файле configs/team.yaml. Откройте его любым текстовым редактором и выполните конфигурацию.

# Разрешено ли пользователям изменять номер телефона в профиле
profile.phone_change_enabled: true

# Разрешено ли пользователям изменять почтовый адрес в профиле
profile.mail_change_enabled: true

# Разрешено ли пользователям изменять Имя Фамилия в профиле
# Данный параметр не влияет на аутентификацию через SSO/LDAP. Если пользователи
# зарегистрировались через SSO/LDAP, то они не смогут изменить Имя Фамилию в приложении.
profile.name_change_enabled: true

# Разрешено ли пользователям изменять аватар в профиле
profile.avatar_change_enabled: true

# Разрешено ли пользователям изменять бейдж в профиле
profile.badge_change_enabled: true

# Разрешено ли пользователям изменять описание в профиле
profile.description_change_enabled: true

# Разрешено ли пользователям изменять статус в профиле
profile.status_change_enabled: true

Запуск установки#

Установщик запускается командой:

sudo python3 script/install.py

Генерация ключей шифрования#

Ключи шифрования служат для создания доверенных данных между клиентскими приложениями и сервером. В интерактивном режиме никакие данные вводить не нужно, ключи сгенерируются автоматически:

Проводим генерацию ключей безопасности
Сгенерировали ключи безопасности по следующему пути: /<installation_dir>/security.yaml

Внимание

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

Ожидание завершения установки#

Развертывание приложения занимает некоторое время. В зависимости от мощности сервера время может варьироваться от 3 до 15 минут. Текущее состояние развертывания можно узнать с помощью команды:

sudo docker service ls | grep -vE "default-file|jitsi-custom"

У всех сервисов правое и левое число в колонке REPLICAS должны совпадать (ниже пример, количество строк и значения в полях могут быть другими):

ID             NAME              MODE         REPLICAS   IMAGE                                                     PORTS
jrnsa5illaao   pivot_nginx       replicated   1/1        dockerhub.com/nginx/nginx:apline-latest                   *:31000->443/tcp
7wismhojfze5   pivot_php_pivot   replicated   1/1        docker.getcompass.com/compass-on-premise/php_pivot:1.1.0
3meydkmdpx3j   pivot_go_event    replicated   1/1        docker.getcompass.com/compass-on-premise/go_event:1.1.0

Если по истечении ожидаемого времени сервис не готов к работе, то можно получить дополнительную информацию командой:

sudo docker service ps <ID_или_NAME_сервиса> --no-trunc

Активация сервера#

Активация сервера создаст связь с сервисами Compass для обеспечения работы push-уведомлений и регистрации лицензий. Активация выполняется один раз, серверы обмениваются секретными ключами, которые затем будут использоваться для доверенных запросов. Для активации выполните команду:

sudo python3 script/activate_server.py

Остановка и запуск сервисов MySQL#

Для корректной остановки и запуска сервисов MySQL в Docker Swarm, используйте следующие команды. Остановка сервисов MySQL:

for service in $(sudo docker service ls | grep mysql | awk '{print $1}'); do sudo docker service scale $service=0; done;

Запуск сервисов MySQL:

for service in $(sudo docker service ls | grep mysql | awk '{print $1}'); do sudo docker service scale $service=1; done;

Внимание

Не перезагружайте сервер, на котором работает база данных MySQL, без предварительной остановки сервисов MySQL. Это может привести к потере данных или нарушению целостности базы.

Создание дополнительных пространств для общения#

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

sudo python3 script/create_team.py

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

Добавление новых экземпляров подключений при использовании пользовательских БД

Примечание

Если вы используете Compass On‑premise в стандартном режиме и не настраивали подключение к пользовательским базам данных, содержимое этого блока можно пропустить.

Для добавления новых пространств для общения при отсутствии свободных экземпляров пользовательских БД необходимо добавить новые параметры подключения к пользовательским БД в конфигурационный файл configs/database.yaml в массив company_mysql_hosts.

# Базы данных команд. Каждой команде необходимо выделить собственную БД.
# Хранит в себе данные переписок, данные карточек сотрудников и данные
# пользовательских файлов.
company_mysql_hosts:

# Ранее созданное подключение 1.
- host: "team.bd.host"
  port: 3306
  root_password: "strong-one-team1"
# Ранее созданное подключение 1.
- host: "team.bd.host"
  port: 3307
  root_password: "strong-one-team2"
# Новое подключение 1.
- host: "team.extra-bd.host"
  port: 3306
  root_password: "strong-one-team3"
# Новое подключение 2.
- host: "team.extra-bd.host"
  port: 3307
  root_password: "strong-one-team4"

После конфигурирования выполнить команду из директории установщика:

sudo python3 script/apply_db_configuration.py

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

Напишите нам в пространстве поддержки On-premise, Telegram или на почту support@getcompass.ru, чтобы получить индивидуальную демонстрацию функционала и помощь по вопросам интеграции мессенджера в вашей компании.