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

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

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

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

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

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

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

cd onpremise-installer

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

python3 script/create_configs.py

После выполнения команды будет создана директория 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-авторизации.

# 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)"

Конфигурация 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 31800/tcp;
sudo ufw allow 31801/tcp;
sudo ufw allow 31802/tcp;
sudo ufw allow 3478/tcp;
sudo ufw allow 5349/tcp;

sudo ufw allow 33000:33999/tcp;
sudo ufw allow 33000:33999/udp;
sudo ufw allow 34000:34999/tcp;
sudo ufw allow 34000:34999/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

# Внешний порт контейнера nginx сервиса аудио- и видеозвонков.
# Данный порт должен быть открыт для внешних запросов (tcp).
janus.service.nginx.external_https_port: 31800

# Внешний порт доступа к медиа-серверу Janus (обеспечивает функционал звонков).
# Данный порт должен быть открыт для внешних запросов (tcp).
janus.service.janus.port: 31801

# Внешний порт для доступа к панели администрирования медиа-сервера Janus.
# Данный порт должен быть открыт для внешних запросов (tcp).
janus.service.janus.admin_port: 31802

# Диапазон портов, которые будут использоваться для установления соединения с Janus.
# Данный порт должен быть открыт для внешних запросов (tcp и udp).
janus.service.janus.rtp_port_from: 33000
janus.service.janus.rtp_port_to: 33999

# Внешний порт для подключения к TURN серверу звонков.
# Данный порт должен быть открыт для внешних запросов (tcp).
janus.service.coturn.external_port: 3478

# Внешний порт для защищенного подключения к TURN серверу звонков.
# Данный порт должен быть открыт для внешних запросов (tcp).
janus.service.coturn.external_tls_port: 5349

# Диапазон портов, которые будут использоваться для установления соединения с Turn-сервером.
# Данный порт должен быть открыт для внешних запросов (tcp и udp).
janus.service.coturn.exchange_port_from: 34000
janus.service.coturn.exchange_port_to: 34999

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

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

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

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

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

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

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

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

Внимание

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

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

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

sudo python3 script/install.py

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

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

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

Внимание

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

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

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

sudo docker service ls | grep -v "default-file"

У всех сервисов правое и левое число в колонке 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

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

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

sudo python3 script/create_team.py

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


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