Установка серверной части приложения#
Данный раздел содержит информацию для быстрого развертывания серверной части приложения с использованием одного физического сервера и одной ноды Docker Swarm.
Загрузка установщика#
Для начала нужно скопировать установщик с git-репозитория. Установщик представляет из себя набор скриптов и файлов-конфигураций, позволяющих быстро настроить и развернуть приложение.
Подготовка установщика#
Перейдите в директорию установщика командой:
Первым шагом необходимо создать конфигурационные файлы для приложения. Для этого необходимо выполнить команду:
После выполнения команды будет создана директория configs внутри директории инсталлятора с файлами настроек приложения.
Конфигурация правил регистрации участников#
Compass On‑premise предлагает следующие способы создания и аутентификации учетных записей:
с использованием номера телефона;
с использованием электронной почты;
с использованием SSO.
Для работы приложения необходимо выбрать как минимум один из способов регистрации/аутентификации.
Соответствующая настройка находится в файле configs/auth.yaml. Откройте его любым текстовым редактором
и укажите желаемый способ.
# Доступные способы аутентификации. Возможные варианты:
# phone_number – по номеру телефона с подтверждением SMS-кода;
# mail – по электронной почте с паролем и кодом подтверждения;
# sso – через сервис Single Sign-On;
available_methods: ["phone_number", "mail", "sso"]
Примечание
Можно указать как один способ, так и несколько. Обратите внимание, что значение всегда должно быть массивом строк, даже если вы выбрали один способ регистрации/аутентификации. В случае указания единственного способа в массиве должен быть один элемент.
Конфигурация Google Recaptcha#
Внимание
С версии 1.7 настройка Google Recaptcha стала обязательной.
Настройки Google Recaptcha находятся в файле configs/auth.yaml. Откройте его любым текстовым редактором
и выполните настройку Google Recaptcha (инструкция подключения).
# Идентификатор проекта Google Recaptcha.
# В документации по подключению Google Recaptcha обозначено как Project ID.
captcha.project_id: "<id проекта из панели управления Google>"
# Серверный ключ Google Recaptcha.
# Данный ключ используется приложением для идентификации в системе Google Recaptcha.
captcha.server_key: "<ваш серверный ключ из панели Google Recaptcha>"
# Кол-во попыток аутентификации, после которых запрашивается разгадывание Recaptcha.
# При значении = 0 – каждая попытка аутентификации запрашивает разгадывание Recaptcha.
captcha.require_after: 2
# Общий ключ Google Recaptcha. Данный ключ будет использоваться
# для всех клиентских платформ, кроме тех, для которых задан выделенный ключ.
# В документации по подключению Google Recaptcha обозначено как общий ключ.
captcha.default_client_key: "<ваш общий ключ из панели Google Recaptcha>"
# Выделенный ключ Google Recaptcha для платформы Android (Google Play).
# Данный ключ будет использоваться только для приложения, установленного через Google Play
# Использование выделенного ключа для Google Play версии приложения является необходимым требованием.
# В документации по подключению Google Recaptcha обозначено как ключ платформы андроид.
captcha.android_client_key: "<ключ платформы Android>"
# Выделенный ключ Google Recaptcha для платформы iOS (Apple Store).
# Данный ключ будет использоваться только для приложения, установленного через AppStore
# Использование выделенного ключа для AppStore версии приложения является необходимым требованием.
# В документации по подключению Google Recaptcha обозначено как ключ платформы iOS.
captcha.ios_client_key: "<ключ платформы iOS>"
Конфигурация почтового сервиса#
Если вы указали электронную почту как способ регистрации/аутентификации, необходимо провести настройку почтового сервиса.
Настройки почтового сервиса находятся в файле 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.
# ID и секретный ключ клиентского приложения, зарегистрированных в SSO провайдере
sso.client_id: "<ваш Client Identifier>"
sso.client_secret: "<ваш Secret>"
# Ссылка на метаданные SSO провайдера
sso.oidc_provider_metadata_link: "<ссылка, по которой доступна meta-data>"
# Сопоставление названия атрибутов учетной записи SSO с атрибутами профиля пользователя в Compass.
# Поля могут быть пустыми, если атрибут не требуется
sso.attribution_mapping.first_name: "<маппинг атрибута имя>"
sso.attribution_mapping.last_name: "<маппинг атрибута фамилия>"
sso.attribution_mapping.mail: "<маппинг атрибута электронная почта>"
sso.attribution_mapping.phone_number: "<маппинг атрибута номер телефона>"
# Кастомизация текста кнопки для запуска аутентификации через SSO на веб-сайте On-Premise решения
sso.web_auth_button_text: "Войти через корп. портал (AD SSO)"
# Включена ли опция альтернативных способов аутентификации при аутентификации через SSO.
# При включенной опции у пользователей прошедших аутентификацию через SSO
# появляется возможность аутентификации через другие способы аутентификации,
# описанных в available_methods в текущем конфигурационном файле.
sso.authorization_alternative_enabled: false
Примечание
Если в дальнейшем потребуется изменить параметры связи с SSO, необходимо повторно отредактировать файл, указав новые значения, и выполнить команду из директории установщика:
Конфигурация 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/tcp;
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
# Порт для компонента jicofo, модуля для ВКС
jitsi.service.jicofo.port: 35001
# Порт для компонента prosody, модуля для ВКС
# Запросы к компоненту будут отправляться на этот порт.
jitsi.service.prosody.serve_port: 35002
Параметры 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
Конфигурация 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: "First Team"
Внимание
Данные конфигурации используются только для регистрации Root‑пользователя и создания первой команды. После успешного создания Root‑пользователя и первой команды изменение этих настроек не приведет к изменению данных в приложении.
Конфигурация разрешения редактирования профилей участников#
С помощью этого раздела конфигурации вы можете ограничить возможность редактирования данных профиля пользователями.
Настройки разрешений находятся в файле configs/team.yaml. Откройте его любым текстовым редактором
и выполните конфигурацию.
# Разрешено ли пользователям изменять номер телефона в профиле
profile.phone_change_enabled: true
# Разрешено ли пользователям изменять почтовый адрес в профиле
profile.mail_change_enabled: true
# Разрешено ли пользователям изменять Имя Фамилия в профиле
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
Запуск установки#
Установщик запускается командой:
Генерация ключей шифрования#
Ключи шифрования служат для создания доверенных данных между клиентскими приложениями и сервером. В интерактивном режиме никакие данные вводить не нужно, ключи сгенерируются автоматически:
Проводим генерацию ключей безопасности
Сгенерировали ключи безопасности по следующему пути: /<installation_dir>/security.yaml
Внимание
После завершения установки будет сгенерирован файл security.yaml с ключами безопасности, необходимыми для корректной работы приложения.
В случае их утраты доступ к ранее сохраненным данным будет утерян. Рекомендуем создать резервную копию файла.
Ожидание завершения установки#
Развертывание приложения занимает некоторое время. В зависимости от мощности сервера время может варьироваться от 3 до 15 минут. Текущее состояние развертывания можно узнать с помощью команды:
У всех сервисов правое и левое число в колонке 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
Если по истечении ожидаемого времени сервис не готов к работе, то можно получить дополнительную информацию командой:
Активация сервера#
Активация сервера создаст связь с сервисами Compass для обеспечения работы push-уведомлений и регистрации лицензий. Активация выполняется один раз, серверы обмениваются секретными ключами, которые затем будут использоваться для доверенных запросов. Для активации выполните команду:
Создание дополнительных пространств для общения#
Теперь вы можете создать несколько новых пространств для общения (но не более 15) с помощью специальной команды. Команду нужно выполнить столько раз, сколько требуется создать пространств.
После создания хотя бы одной команды, вы сможете приступить к использованию приложения. Дополнительная информация о работе с приложением доступна в разделе Начало работы.
Напишите нам в пространстве поддержки On-premise, Telegram, WhatsApp или на почту support@getcompass.ru, чтобы получить индивидуальную демонстрацию функционала и помощь по вопросам интеграции мессенджера в вашей компании.