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

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

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

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

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

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

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

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

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

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

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

^ Настройка ^ Что указать ^
| ''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''.

Пример:

<code>
SYSTEMD_SERVICE_NAME=sharix_main
</code>

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

<code>
systemctl restart sharix_main.service
</code>

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

Пример:

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

<code>
PLATFORM_INTEGRATION=1
</code>

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

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

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

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

Если в ''.env'':

<code>
DEFAULT_CLIENT_ROLE=METASERVICE-CLIENT
PLATFORM_INTEGRATION=1
</code>

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

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

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

===== 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''.
  - Перезапустить сервис.