documentation/pages/lk-manual.md

# Создание Интеллектуального модуля на платформе

Данная инструкция описывает создание приложения через Личный Кабинет Разработчика (далее используется краткая версия `ЛК`): `https://platform.stratpro.hse.ru/cabinet/`  
Инструкция охватывает этапы от создания шаблонного приложения в ЛК до развертывания собственного кода.  

Инструкция предполагает, что все необходимые доступы уже получены:  
- аккаунт в KeyCloack: `https://platform-sso.stratpro.hse.ru`  

Проверьте, что у вас есть доступ к ресурсам:  
- доступ в Forgejo: `https://platform-forgejo.stratpro.hse.ru`
- доступ в Harbor: `https://platform-reg.stratpro.hse.ru`


Оглавление:
- [1. Управление командами](lk-manual.md#1-управление-командами)
- [2. Создание приложения](lk-manual.md#2-создание-приложения)
- [3. Развертывание своего приложения на основе шаблона](lk-manual.md#3-развертывание-своего-приложения-на-основе-шаблона)

## 0. Перейдите в Личный Кабинет

> Перейдите по ссылке `https://platform.stratpro.hse.ru/cabinet/`.   

![Главная страница ЛК](../images/image-1.png)

## 1. Управление командами

Перейдите во вкладку `Команды`:

![alt text](../images/image-2.png)

После перехода вы увидите страницу управления вашими командами.

![alt text](../images/image-3.png)

Здесь вы можете:
- добавить разработчика в свою команду
- изменить роль разработчика в вашей команде
- удалить разработчика из своей команды
- создать новую команду

### 1.1. Добавление разработчика в команду

Нажмите на свою команду - вы перейдёте на страницу управления командой:

![alt text](../images/image-4.png)

Нажмите `Пригласить участника`

![alt text](../images/image-5.png)

Введите e-mail и роль участника.  

### 1.2. Изменить роль разработчика в команде

В экране управления командой наведите мышь на разработчика — появится кнопка редактирования:

![alt text](../images/image-7.png)

После нажатия откроется окно редактирования:

![alt text](../images/image-8.png)

### 1.3. Удалить разработчика из команды

В экране управления командой наведите мышь на разработчика — появится кнопка удаления:

![alt text](../images/image-9.png)

#### 1.4. Создание команды

В основной панели управления командами нажмите кнопку `Добавить команду`.

![alt text](../images/image-10.png)

Заполните поля:

- `Название команды` 
- `Код команды` — код, который будет использоваться при создании приложений, а также станет частью ссылки в API ваших приложений. Старайтесь делать его коротким.
- `Список участников`

## 2. Создание приложения

На странице `Приложения` нажмите кнопку `Добавить приложение`.

![alt text](../images/image-12.png)

вы перейдёте на страницу создания приложения.

![alt text](../images/image-13.png)

Заполните поля:

- `Команда` — объединение разработчиков, которые будут иметь доступ к изменению и управлению приложением. Изначально у каждого нового пользователя уже есть своя команда.
- `Код приложения` — код, который будет использоваться при создании приложения, а также станет частью ссылки API вашего приложения.
- `Название приложения`
- `Описание приложения`
- `Шаблон` — шаблон первой версии вашего приложения. На данный момент доступен только `Стандартный`, включающий в себя мини-пример сервиса `echo`.

Пример заполнения:

![alt text](../images/image-14.png)

После нажатия кнопки `Создать` платформа начнёт процесс создания ваших ресурсов для вашего приложения. Отслеживать процесс создания можно по событиям:

![alt text](../images/image-15.png)

Если что-то пойдёт не так на этом этапе, это станет понятно по событиям. Пример:

![alt text](../images/image-16.png)

В таком случае обратитесь в поддержку: `https://pmo.hse.ru/servicedesk/customer/portal/192`

После окончания создания приложения появится кнопка `Запустить`, а также ресурсы приложения рядом с кнопкой.

![alt text](../images/image-17.png)

Ресурсы приложения:
- `репозиторий в Harbor` — для образов приложения
- `репозиторий в Forgejo` — для исходников кода приложения, а также дальнейшего управления ресурсами развернутого приложения
- `дашборды Grafana` — для мониторинга состояния развернутого приложения и просмотра его логов

> Обратите внимание на строку `pu-msgalynchik-pa-manual-1`. В этом же месте будет написан полный код вашего приложения. Это namespace в Kubernetes, в котором будет развернуто ваше приложение, а также часть ссылки для любого его API.

Нажмите кнопку `Запустить`:

![alt text](../images/image-18.png)

Начнётся процесс развертывания приложения, его также можно отслеживать по событиям. Когда приложение будет готово, вы увидите зелёный статус рядом с именем приложения.

![alt text](../images/image-19.png)

Обратите внимание на уведомление. Если при создании приложения у вас возникают технические вопросы, обращайтесь к [документации](https://platform-forgejo.stratpro.hse.ru/mlops_platform/documentation/src/branch/main/README.md).

Приложение развернуто! Теперь вы можете проверить, что оно действительно работает, запросив OpenAPI-схему развернутого echo-примера:

```
https://platform.stratpro.hse.ru/{код приложения}/{путь к api сервиса}/modelversion
```

- `код приложения` можно увидеть под `Именем приложения` в ЛК или в манифестах из app/ в поле namespace
- `путь к api сервиса`  можно найти в манифесте api вашего mlcmp (в шаблонном приложении это файл `mlcmp-api.template.yaml`). В манифесте API `путь к api сервиса` указан в поле `spec/restfulApi/path`.

Для приложения, которое было развернуто в этой инструкции, это:

```
https://platform.stratpro.hse.ru/pu-msgalynchik-pa-manual-1/pu-msgalynchik-pa-manual-1-hello/modelversion
```

## 3. Развертывание своего приложения на основе шаблона

> выполняйте только после проверки, что предыдущий пункт выполнен успешно и ссылка возвращает OpenAPI-схему.

Склонируйте себе репозиторий приложения. Для примера:

```
git clone https://platform-forgejo.stratpro.hse.ru/pu-msgalynchik-pa-manual-1/pu-msgalynchik-pa-manual-1-user.git
```

Добавьте свой код. Здесь в качестве примера используется mnist.

![alt text](../images/image-20.png)

Отправьте изменения в репозиторий Forgejo:

```bash
git add --all
git commit -m "Add mnist"
git push
```
Для того, чтобы изменения попали в контейнер приложения, необходимо создать тег:

```bash
git tag v1.0.1
git push --tags
```

После этого проверьте, что контейнер был собран. Перейдите в Harbor по ссылке из ЛК. В разделе `Projects` нажмите на свой проект. Убедитесь, что контейнер с указанным вами тегом появился:

![alt text](../images/image-21.png)


Добавьте `mnist-api.yaml` в папку `app/`. Пример для приложения инструкции:

```yaml
apiVersion: "unified-platform.cs.hse.ru/v1"
kind: APIComponent
metadata:
  name: mnist-api
  namespace: pu-msgalynchik-pa-manual-1
spec:
  published: true
  mlComponent:
    name: mnist-mlcmp
  restfulApi:
    path: pu-msgalynchik-pa-manual-1-mnist
    auth:
      identityPassThrough: true
      oidc:
         groups: ["/pu-msgalynchik-pa-manual-1"]
```

Этот компонент предоставляет API для вашего нового сервиса.

Добавьте `mnist-mlcmp.yaml` в папку `app/`. Пример для приложения инструкции:

```yaml
apiVersion: "unified-platform.cs.hse.ru/v1"
kind: MLComponent
metadata:
  name: mnist-mlcmp
  namespace: pu-msgalynchik-pa-manual-1
spec:
  image:
    existingImageName: platform-reg.stratpro.hse.ru/pu-msgalynchik-pa-manual-1/pu-msgalynchik-pa-manual-1-user:v1.0.1
  resourceLimits:
    cpu: 500m
    memory: 256M
  env:
    - name: MNIST_SAVE_MODEL_PATH
      value: "/home/echo/models/default/model.joblib"
    - name: MNIST_INFERENCE_WORKDIR
      value: "/home/echo/users/tmp"
  mlService:
    packageRegistryName: unified-platform-resources-packages-repository
    inference:
      fileExchange:
        fileBox: user-box
        inferenceFilesPath: /home/echo/users/tmp
      model:
        modelBox: model-box
        modelPath: /home/echo/models/mnist/model.joblib
      entryPoint:
        pythonPath: .
        pythonFunction: mnist.predict.inference
  connectedBoxes:
    - name: model-box
      path: /home/echo/models/mnist
      mountS3Box:
        subPath: users/admin/file_groups/mnist
        s3BoxName:  models
    - name: user-box
      copyS3Box:
        s3BoxName: users
```
Этот компонент создаёт и разворачивает контейнер из вашего Docker-образа. Для подробной документации обратитесь к странице [Компонент MLComponent](./pages/mlcmp.md).

Отправьте изменения в Forgejo:

```
git add --all
git commit -m "Deploy mnist"
git push
```

После этого Платформа развернёт ваше приложение!