Содержание

Подключение своего ShariX Open к Платформе ShariX

Подключение своего ShariX Open к Платформе ShariX

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

Что получится после настройки

После подключения:

сервис появится на платформе;
владелец сервиса получит права администратора сервиса;
пользователи смогут подключать сервис через платформу;
новые пользователи смогут регистрироваться на сервисе с синхронизацией профиля;
изменения профиля и пароля смогут передаваться через платформу на другие подключенные сервисы.

1. Подготовьте сервис

Выполняется на сервере, где установлен ShariX Open.

Откройте файл .env сервиса и проверьте настройки.

Для первичного подключения рекомендуется:

DEBUG=True
PLATFORM_INTEGRATION=2
PLATFORM_API_URL=https://адрес-платформы/my/api/
DEFAULT_CLIENT_ROLE=METASERVICE-CLIENT
SYSTEMD_SERVICE_NAME=sharix_main

Что означает каждая настройка:

Настройка	Что указать
`DEBUG=True`	Удобно на этапе разворачивания: сервис сможет показывать сгенерированный ключ для переноса на платформу. После настройки лучше вернуть `False`.
`PLATFORM_INTEGRATION=2`	Подготовительный режим. Сервис уже пробует синхронизацию, но еще не считается полностью активным.
`PLATFORM_API_URL`	Адрес API платформы. Пример: `https://testpm1.sharix-app.org/my/api/`.
`DEFAULT_CLIENT_ROLE`	Роль пользователя при самостоятельной регистрации на сервисе. Обычно `METASERVICE-CLIENT`.
`SYSTEMD_SERVICE_NAME`	Имя systemd-сервиса без `.service`. Нужно для перезапуска через веб-интерфейс. Например, если systemd-сервис называется `sharix_main.service`, укажите `sharix_main`.

Возможные значения DEFAULT_CLIENT_ROLE:

Значение	Когда использовать
`METASERVICE-CLIENT`	Обычный вариант. Зарегистрированный пользователь становится клиентом сервиса.
`METASERVICE-GUEST`	Пользователи создаются только локально, без синхронизации с платформой.
`METASERVICE-CORPCLIENT`	Регистрация используется как заявка на корпоративное обслуживание.

После изменения .env перезапустите сервис.

Если доступен веб-интерфейс администратора:

Войдите в Django admin сервиса.
Откройте раздел Visual settings.
Нажмите кнопку Перезапустить сервис.
Подтвердите перезапуск.

Если кнопка перезапуска не работает, проверьте SYSTEMD_SERVICE_NAME в .env. Значение должно совпадать с именем systemd-сервиса без .service.

Пример:

SYSTEMD_SERVICE_NAME=sharix_main

Для ручного перезапуска через сервер:

systemctl restart sharix_main.service

2. Сгенерируйте на сервисе ключ для платформы

Выполняется в интерфейсе сервиса ShariX Open.

Войдите на сервис под администратором.
Откройте кабинет метасервиса.
Нажмите кнопку генерации API-ключа для платформы.
Скопируйте полученный ключ.

Этот ключ нужен платформе, чтобы обращаться к вашему сервису.

Если DEBUG=True, ключ может отображаться в кабинете сервиса, чтобы его было удобно скопировать.

Если DEBUG=False, ключ может быть показан только один раз сразу после генерации. Скопируйте его сразу.

3. Создайте сервис на платформе

Выполняется на Платформе ShariX.

Войдите на платформу под пользователем, который будет владельцем сервиса.
Откройте раздел создания сервиса.
Создайте сервис и заполните основные данные:
- название;
- юридическое название;
- ИНН;
- реквизиты;
- описание;
- адрес сайта сервиса.

На этапе первичного создания на платформе может не быть поля для ключа синхронизации. Это нормально.

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

4. Заполните на платформе данные для связи с сервисом

Выполняется на платформе, в карточке или форме редактирования созданного сервиса.

Нужно заполнить два значения.

Что заполнить на платформе	Что туда вставить
API URL сервиса	Адрес API вашего сервиса. Например: `https://open.example.org/my/api/`.
Ключ доступа к сервису / ключ синхронизации	Ключ, который вы сгенерировали на сервисе на шаге 2.

Пример:

API URL сервиса: https://open.example.org/my/api/
Ключ доступа к сервису: скопированный_ключ_с_сервиса

Сохраните карточку сервиса.

5. Передайте сервису ключ платформы

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

Этот ключ должен попасть на сервис в .env:

PLATFORM_API_KEY=ключ_выданный_платформой

Также сервис должен знать свой ID на платформе:

METASERVICE_ID=ID_сервиса_на_платформе

Есть два способа заполнить эти значения.

Способ 1. Автоматически через кнопку на платформе

Используйте этот способ, если уже заполнены:

API URL сервиса;
ключ доступа платформы к сервису;
сервис доступен с платформы.

В карточке или форме редактирования сервиса на платформе нажмите кнопку обновления настроек сервиса, если она доступна.

После этого платформа сама запишет на сервис в .env:

METASERVICE_ID=ID_сервиса_на_платформе
PLATFORM_API_KEY=ключ_выданный_платформой

После записи настроек перезапустите сервис.

На сервисе это можно сделать через:

Django admin;
Visual settings;
кнопку Перезапустить сервис.

Способ 2. Вручную через .env

Если автоматическая кнопка недоступна или не сработала, внесите значения вручную в .env сервиса:

METASERVICE_ID=ID_сервиса_на_платформе
PLATFORM_API_KEY=ключ_выданный_платформой

После этого перезапустите сервис.

6. Назначьте администратора сервиса

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

Обычно это происходит после сохранения настроек интеграции на платформе.

В результате на сервисе должно быть так:

пользователь-владелец сервиса создан или обновлен;
у него есть роль METASERVICE-ADMIN;
тестовый пользователь 2101 больше не является METASERVICE-ADMIN;
других лишних METASERVICE-ADMIN нет.

Проверьте это в кабинете метасервиса на сервисе.

Если на сервисе найдено больше одного METASERVICE-ADMIN, в кабинете должно появиться предупреждение и кнопки для снятия лишних прав.

Оставьте одного администратора сервиса.

7. Проверьте состояние подключения

На сервисе проверьте .env:

PLATFORM_INTEGRATION=2
PLATFORM_API_URL=https://адрес-платформы/my/api/
METASERVICE_ID=ID_сервиса_на_платформе
PLATFORM_API_KEY=ключ_выданный_платформой

На платформе в карточке сервиса проверьте:

API URL сервиса заполнен;
ключ доступа к сервису заполнен;
сервис не находится в аварийном режиме;
текущий владелец сервиса соответствует администратору на сервисе.

На сервисе проверьте:

кабинет метасервиса открывается;
нет предупреждения о нескольких METASERVICE-ADMIN;
Testkit, если подключен, открывается;
регистрация пользователя работает.

8. Переведите сервис в активный режим

Когда все проверки прошли успешно, измените на сервисе .env:

PLATFORM_INTEGRATION=1

Перезапустите сервис.

После этого сервис работает в активном режиме синхронизации.

9. Проверьте регистрацию пользователя

Проверьте сценарий самостоятельной регистрации на сервисе.

Если в .env:

DEFAULT_CLIENT_ROLE=METASERVICE-CLIENT
PLATFORM_INTEGRATION=1

то на форме регистрации пользователь сможет выбрать синхронизацию с платформой.

Ожидаемое поведение:

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

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

Выполняется на платформе.

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

Ожидаемое поведение:

платформа создаст или обновит пользователя на сервисе;
на платформе появится активная связь пользователя с сервисом;
на сервисе у пользователя появится запись клиента;
синхронизация профиля будет включена.

11. Проверьте синхронизацию профиля

На сервисе откройте профиль пользователя.

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

Проверьте:

Включите синхронизацию.
Измените имя или email.
Сохраните профиль.
Проверьте, что изменение появилось на платформе.

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

Если какой-то сервис не принял изменение:

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

12. Проверьте смену пароля

На сервисе смените пароль пользователя.

Если синхронизация включена:

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

Если один из связанных сервисов недоступен:

пароль у пользователя все равно меняется;
недоступный сервис переводится в аварийный режим;
пользователь получает предупреждение о проблеме синхронизации.

13. Если сервис попал в аварийный режим

Аварийный режим означает, что платформа пыталась синхронизироваться с сервисом, но сервис не ответил корректно.

Проверьте по порядку:

Открывается ли сервис в браузере.
Правильно ли указан API URL сервиса на платформе.
Правильно ли вставлен ключ доступа к сервису на платформе.
Правильно ли указан PLATFORM_API_URL на сервисе.
Есть ли на сервисе METASERVICE_ID.
Есть ли на сервисе PLATFORM_API_KEY.
Ровно ли один пользователь имеет роль METASERVICE-ADMIN.
Перезапущен ли сервис после изменения .env.

После исправления снова сохраните настройки интеграции на платформе или повторите проверку подключения.

14. Короткий порядок действий

На сервисе в .env указать DEBUG=True, PLATFORM_INTEGRATION=2, PLATFORM_API_URL, DEFAULT_CLIENT_ROLE, SYSTEMD_SERVICE_NAME.
Перезапустить сервис.
На сервисе сгенерировать ключ доступа платформы к сервису.
На платформе создать сервис.
На платформе открыть созданный сервис и заполнить API URL сервиса.
На платформе вставить ключ, сгенерированный на сервисе.
Сохранить сервис.
На платформе обновить настройки сервиса, чтобы на сервис попали METASERVICE_ID и PLATFORM_API_KEY.
Перезапустить сервис.
Проверить, что владелец стал единственным METASERVICE-ADMIN на сервисе.
Проверить регистрацию пользователя.
Проверить подключение пользователя с платформы.
Проверить изменение профиля.
Проверить смену пароля.
Перевести сервис в PLATFORM_INTEGRATION=1.
Перезапустить сервис.