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

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

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

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

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

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

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

cd onpremise-installer

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

python3 script/create_configs.py

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

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

Примечание

Если вы не планируете использовать Google Recaptcha, этот пункт можно пропустить — Google Recaptcha по умолчанию отключена.

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

# Флаг включения Google Recaptcha, возможные значения: 1 — включена, 0 — выключена.
# Если Google Recaptcha включена, то поля default_client_key и server_key должны быть заданы.
is_enabled: 1

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

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

# Идентификатор проекта Google Recaptcha.
# В документации по подключению Google Recaptcha обозначено как Project Name.
#
# Тип данных: строка
# Пример: project_id: example_project_id
project_id: <id проекта из панели управления Google>

Для платформ Android и iOS необходимо задать выделенные ключи.

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

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

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

# Выделенные ключи клиентских платформ.
# Не являются обязательными, в большинстве случаев их указывать нет необходимости.
huawei.client_key:
electron.client_key:

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

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

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

# Флаг включения SMS, возможные значения: 1 — включена, 0 — выключена.
# Если SMS включены, то конфигурация как минимум одного провайдера должна быть заполнена.
is_enabled: 0
Настройка 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) пользователя в приложении.
# Телефон указывается в международном формате (с «+» в начале).
# В дальнейшем номер можно будет изменить в интерфейсе приложения.
# Номер должен быть настоящим — без него невозможно будет выполнить вход в приложение.
root_user.phone_number: +79123456789

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

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

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

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

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

sudo python3 script/create_team.py

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


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